ForthClear Liquidation Marketplace

Search available liquidation inventory with filters

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Search query"
    },
    "category": {
      "type": "string",
      "description": "Product category"
    },
    "condition": {
      "type": "string",
      "enum": [
        "salvage",
        "customer_returns",
        "shelf_pulls",
        "overstock",
        "new_or_refurbished"
      ],
      "description": "Standard liquidation condition grade (Task #72)"
    },
    "max_price": {
      "type": "integer",
      "description": "Maximum price in cents"
    },
    "limit": {
      "type": "integer",
      "default": 20,
      "maximum": 100,
      "description": "Maximum listings to return (default 20, max 100)."
    }
  }
}

{
  "type": "object",
  "properties": {
    "products": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Opaque listing id, `product_<n>`."
          },
          "name": {
            "type": "string"
          },
          "category": {
            "type": "string"
          },
          "condition": {
            "type": [
              "string",
              "null"
            ]
          },
          "quantity": {
            "type": "integer"
          },
          "price": {
            "type": "integer",
            "description": "Unit price in cents."
          },
          "discount_percent": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Null when the listing has no original retail price on file."
          }
        },
        "required": [
          "id",
          "name",
          "category",
          "quantity",
          "price"
        ]
      }
    },
    "total": {
      "type": "integer",
      "description": "Catalogue matches before the limit is applied."
    },
    "message": {
      "type": "string"
    }
  },
  "required": [
    "products",
    "total",
    "message"
  ]
}

Get detailed information about a specific product

{
  "type": "object",
  "properties": {
    "product_id": {
      "type": "string",
      "description": "Product ID (format: product_123)"
    }
  },
  "required": [
    "product_id"
  ]
}

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "description": {
      "type": [
        "string",
        "null"
      ]
    },
    "category": {
      "type": "string"
    },
    "condition": {
      "type": [
        "string",
        "null"
      ]
    },
    "quantity_available": {
      "type": "integer"
    },
    "price": {
      "type": "integer",
      "description": "Unit price in minor units of currency."
    },
    "currency": {
      "type": "string"
    },
    "instant_checkout": {
      "type": "boolean"
    },
    "quote_quantity_threshold": {
      "type": "integer"
    },
    "next_action": {
      "type": "string"
    },
    "payment_readiness": {
      "type": "string"
    },
    "original_retail": {
      "type": [
        "integer",
        "null"
      ]
    },
    "seller": {
      "type": "object",
      "properties": {
        "company": {
          "type": "string"
        },
        "verified": {
          "type": "boolean",
          "description": "True once the seller has a Stripe account."
        }
      },
      "required": [
        "company",
        "verified"
      ]
    },
    "quote_required": {
      "type": "boolean"
    }
  },
  "required": [
    "id",
    "name",
    "category",
    "quantity_available",
    "price",
    "quote_required"
  ]
}

Request a bulk quote for a product (buyer tool)

{
  "type": "object",
  "properties": {
    "product_id": {
      "type": "string",
      "description": "Product ID (format: product_123)"
    },
    "quantity": {
      "type": "integer",
      "minimum": 1,
      "description": "Number of units to quote"
    },
    "buyer_email": {
      "type": "string",
      "format": "email",
      "description": "Buyer's email address (required)"
    },
    "buyer_name": {
      "type": "string",
      "description": "Buyer's full name"
    },
    "buyer_company": {
      "type": "string",
      "description": "Buyer's company name"
    },
    "target_price": {
      "type": "integer",
      "description": "Target price per unit in cents (optional)"
    },
    "message": {
      "type": "string",
      "description": "Additional message to seller"
    }
  },
  "required": [
    "product_id",
    "quantity",
    "buyer_email"
  ]
}

{
  "type": "object",
  "properties": {
    "success": {
      "type": "boolean"
    },
    "message": {
      "type": "string"
    },
    "quote": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer"
        },
        "product_id": {
          "type": "string"
        },
        "product_name": {
          "type": "string"
        },
        "quantity": {
          "type": "integer"
        },
        "target_price": {
          "type": [
            "number",
            "null"
          ],
          "description": "Buyer target per unit, as supplied."
        },
        "status": {
          "type": "string"
        },
        "expected_response": {
          "type": "string",
          "description": "Human-readable SLA, e.g. \"24-48 hours\"."
        },
        "seller_company": {
          "type": "string"
        }
      },
      "required": [
        "id",
        "product_id",
        "product_name",
        "quantity",
        "status",
        "expected_response"
      ]
    }
  },
  "required": [
    "success",
    "message",
    "quote"
  ]
}

Create a new product listing (seller tool)

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Listing title shown to buyers and matched by catalogue search."
    },
    "description": {
      "type": "string",
      "description": "Listing body copy: condition detail, packaging, lot composition. Buyers filter on its presence and agents summarise it."
    },
    "category": {
      "type": "string",
      "enum": [
        "electronics",
        "apparel",
        "home_goods",
        "beauty",
        "sports",
        "kitchenware",
        "office_supplies",
        "toys",
        "food_beverage",
        "tools",
        "other"
      ],
      "description": "Catalogue category. One of: electronics, apparel, home_goods, beauty, sports, kitchenware, office_supplies, toys, food_beverage, tools, other."
    },
    "condition": {
      "type": "string",
      "enum": [
        "salvage",
        "customer_returns",
        "shelf_pulls",
        "overstock",
        "new_or_refurbished"
      ],
      "description": "Standard liquidation condition grade (Task #72)"
    },
    "quantity": {
      "type": "integer",
      "minimum": 1,
      "description": "Units available in this lot."
    },
    "price_per_unit": {
      "type": "integer",
      "description": "Price in cents"
    },
    "original_retail_price": {
      "type": "integer",
      "description": "Original retail price in cents"
    },
    "sku": {
      "type": "string",
      "description": "Seller's own stock-keeping unit, shown to buyers and used for reconciliation."
    }
  },
  "required": [
    "name",
    "category",
    "condition",
    "quantity",
    "price_per_unit"
  ]
}

{
  "type": "object",
  "properties": {
    "success": {
      "type": "boolean"
    },
    "message": {
      "type": "string"
    },
    "listing": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "category": {
          "type": "string"
        },
        "condition": {
          "type": [
            "string",
            "null"
          ]
        },
        "quantity": {
          "type": "integer"
        },
        "price": {
          "type": "integer",
          "description": "Unit price in cents."
        },
        "original_retail": {
          "type": [
            "integer",
            "null"
          ]
        },
        "sku": {
          "type": [
            "string",
            "null"
          ]
        },
        "status": {
          "type": "string"
        },
        "image_url": {
          "type": [
            "string",
            "null"
          ]
        },
        "view_url": {
          "type": "string",
          "description": "Buyer-facing listing page."
        }
      },
      "required": [
        "id",
        "name",
        "category",
        "quantity",
        "price",
        "status",
        "view_url"
      ]
    }
  },
  "required": [
    "success",
    "message",
    "listing"
  ]
}

Get AI-powered pricing recommendation for inventory (seller tool)

{
  "type": "object",
  "properties": {
    "category": {
      "type": "string",
      "enum": [
        "electronics",
        "apparel",
        "home_goods",
        "beauty",
        "sports",
        "kitchenware",
        "office_supplies",
        "toys",
        "food_beverage",
        "tools",
        "other"
      ],
      "description": "Catalogue category. One of: electronics, apparel, home_goods, beauty, sports, kitchenware, office_supplies, toys, food_beverage, tools, other."
    },
    "condition": {
      "type": "string",
      "enum": [
        "salvage",
        "customer_returns",
        "shelf_pulls",
        "overstock",
        "new_or_refurbished"
      ],
      "description": "Standard liquidation condition grade (Task #72)"
    },
    "original_retail": {
      "type": "integer",
      "description": "Original retail price in cents"
    },
    "quantity": {
      "type": "integer",
      "description": "Lot size being priced; recommendations scale with volume."
    }
  },
  "required": [
    "category",
    "condition",
    "original_retail"
  ]
}

{
  "type": "object",
  "properties": {
    "recommended_price": {
      "type": "number"
    },
    "price_range": {
      "type": "object",
      "properties": {
        "low": {
          "type": "number"
        },
        "high": {
          "type": "number"
        }
      },
      "required": [
        "low",
        "high"
      ]
    },
    "discount_from_retail": {
      "type": "number",
      "description": "Percent below original retail."
    },
    "factors": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "tips": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "recommended_price",
    "price_range",
    "discount_from_retail",
    "factors",
    "tips"
  ]
}

Get pending quote requests for seller's products (seller tool)

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "pending",
        "responded",
        "all"
      ],
      "default": "pending",
      "description": "Which of the calling seller's quote requests to return: pending (awaiting a reply), responded, or all."
    }
  }
}

{
  "type": "object",
  "properties": {
    "quotes": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "product_id": {
            "type": "string"
          },
          "product_name": {
            "type": "string"
          },
          "buyer_company": {
            "type": "string"
          },
          "quantity": {
            "type": "integer"
          },
          "target_price": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Buyer target in cents."
          },
          "message": {
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "description": "ISO-8601 timestamp."
          }
        },
        "required": [
          "id",
          "product_id",
          "quantity",
          "status",
          "created_at"
        ]
      }
    },
    "total": {
      "type": "integer"
    },
    "message": {
      "type": "string"
    }
  },
  "required": [
    "quotes",
    "total",
    "message"
  ]
}

Respond to a buyer's quote request (seller tool)

{
  "type": "object",
  "properties": {
    "quote_request_id": {
      "type": "integer",
      "description": "Id of the quote request to answer, as returned by get_quote_requests."
    },
    "action": {
      "type": "string",
      "enum": [
        "accept",
        "counter",
        "decline"
      ],
      "description": "accept the buyer's terms as asked, counter with a different price (requires counter_price), or decline the request."
    },
    "counter_price": {
      "type": "integer",
      "description": "Counter offer price in cents (for counter action)"
    },
    "message": {
      "type": "string",
      "description": "Optional note sent to the buyer alongside the decision."
    }
  },
  "required": [
    "quote_request_id",
    "action"
  ]
}

Bulk update prices or minimum order quantities across up to 200 of the calling seller's product listings. Thin adapter over POST /api/products/bulk-update-price and /bulk-update-moq — same seller-ownership filter and per-product validation. Choose mode='price_set' (value=USD), 'price_percent_increase' / 'price_percent_decrease' (value=percent), or 'moq_set' (value=integer units).

{
  "type": "object",
  "properties": {
    "product_ids": {
      "type": "array",
      "items": {
        "type": "integer",
        "minimum": 1
      },
      "minItems": 1,
      "maxItems": 200,
      "description": "ForthClear product ids to update (max 200/request)."
    },
    "mode": {
      "type": "string",
      "enum": [
        "price_set",
        "price_percent_increase",
        "price_percent_decrease",
        "moq_set"
      ],
      "description": "What to change and how: price_set writes an absolute USD price, price_percent_increase / price_percent_decrease adjust the current price by a percentage, moq_set writes a minimum order quantity."
    },
    "value": {
      "type": "number",
      "description": "USD price for price_set, percent (0-1000) for percent modes, integer units (1-999999) for moq_set."
    }
  },
  "required": [
    "product_ids",
    "mode",
    "value"
  ]
}

Mark up to 200 of the calling seller's orders as shipped, optionally writing a shared tracking number / URL / carrier to every order. Thin adapter over POST /api/seller/orders/bulk-mark-shipped — same per-order ownership filter, idempotent re-runs, auto-detected carrier when only a tracking number is supplied. Returns per-order success/failure buckets.

{
  "type": "object",
  "properties": {
    "order_ids": {
      "type": "array",
      "items": {
        "type": "integer",
        "minimum": 1
      },
      "minItems": 1,
      "maxItems": 200,
      "description": "Order ids belonging to the calling seller (max 200/request). Orders owned by anyone else are skipped."
    },
    "tracking_number": {
      "type": "string",
      "maxLength": 255,
      "description": "Tracking number written to every listed order. Supplying this without carrier_name auto-detects the carrier."
    },
    "tracking_url": {
      "type": "string",
      "maxLength": 2000,
      "description": "Tracking URL written to every listed order."
    },
    "carrier_name": {
      "type": "string",
      "maxLength": 255,
      "description": "Carrier for the shipment. Omit to infer it from tracking_number."
    }
  },
  "required": [
    "order_ids"
  ]
}

Export the calling seller's orders as CSV (Order ID, Product, Buyer, Quantity, Total, Status, Date). Thin adapter over POST /api/seller/orders/bulk-export — orders not owned by the caller are silently skipped. Returns the CSV body as a string plus the suggested filename.

{
  "type": "object",
  "properties": {
    "order_ids": {
      "type": "array",
      "items": {
        "type": "integer",
        "minimum": 1
      },
      "minItems": 1,
      "maxItems": 200,
      "description": "Order ids belonging to the calling seller (max 200/request). Orders owned by anyone else are skipped."
    }
  },
  "required": [
    "order_ids"
  ]
}

Read-only digest of the calling seller's inbox: pending quote requests, orders at risk of missing their ship-by deadline, and orders with reported issues. Useful for a daily standup or cron-driven agent that decides which bulk action to run next.

{
  "type": "object",
  "properties": {
    "window_hours": {
      "type": "integer",
      "minimum": 1,
      "maximum": 168,
      "default": 24,
      "description": "Look-ahead window for ship-by-date risk detection (default 24h)."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "default": 10,
      "description": "Max items to surface in each bucket."
    }
  }
}

One-step purchase for products with instant checkout enabled (seller opt-in) and orders under bulk threshold. For products without instant checkout or larger orders, use request_quote instead.

{
  "type": "object",
  "properties": {
    "product_id": {
      "type": "string",
      "description": "Product ID (format: product_123)"
    },
    "quantity": {
      "type": "integer",
      "minimum": 1,
      "description": "Number of units to purchase"
    },
    "buyer_email": {
      "type": "string",
      "format": "email",
      "description": "Buyer's email address"
    },
    "buyer_name": {
      "type": "string",
      "description": "Buyer's full name"
    },
    "buyer_company": {
      "type": "string",
      "description": "Buyer's company name"
    }
  },
  "required": [
    "product_id",
    "quantity",
    "buyer_email"
  ]
}