ForthClear Liquidation Marketplace
Search surplus and overstock inventory, request bulk quotes, and check out.
사용해야 할까요
품질 및 안전성
도구 정의와 프로토콜 준수에 대한 자동 분석을 기반으로 합니다.
컨텍스트 비용
이는 서버의 도구가 모델의 컨텍스트에 로드될 때마다 소비되는 대략적인 토큰 수입니다. 수치가 높을수록 다른 작업에 사용할 수 있는 주의가 줄어듭니다.
설치
원클릭 설치
`claude_desktop_config.json` 파일에 다음을 추가하세요:
{
"mcpServers": {
"liquidation": {
"url": "https://app.forthclear.io/mcp"
}
}
}원격 엔드포인트
https://app.forthclear.io/mcpstreamable-http할 수 있는 일
도구 목록
도구 (30)
🟢search_inventory(query, q, category, condition, max_price, ...)
Keyword search of published, in-stock surplus listings. No sign-in required. `query` matches the name, description, brand, SKU, and category words, in any order. If the whole query is a category (electronics, clothes, home goods), it is treated as that category filter. Pass `category` as a catalogue category, such as electronics or home_goods, when you want to limit results. `max_price` is the maximum unit price in cents. `condition` is salvage, customer_returns, shelf_pulls, overstock, or new_or_refurbished. Name, brand, and SKU matches rank above description matches. For a sentence about what you want, use search_inventory_semantic.
입력 스키마
{
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Words to match, or a category name such as electronics or clothes. Not a sentence — use search_inventory_semantic for that. `q` is accepted as an alias."
},
"q": {
"type": "string",
"description": "Alias for query."
},
"category": {
"type": "string",
"enum": [
"electronics",
"apparel",
"home_goods",
"beauty",
"sports",
"kitchenware",
"office_supplies",
"toys",
"food_beverage",
"tools",
"other"
],
"description": "Limit to one catalogue category. One of: electronics, apparel, home_goods, beauty, sports, kitchenware, office_supplies, toys, food_beverage, tools, other. Prose such as \"Electronics\" or \"clothes\" is accepted and mapped to the stored value."
},
"condition": {
"type": "string",
"enum": [
"salvage",
"customer_returns",
"shelf_pulls",
"overstock",
"new_or_refurbished"
],
"description": "Condition of the goods: salvage (sold as-is), customer returns, shelf pulls, overstock, or new or refurbished."
},
"max_price": {
"type": "integer",
"description": "Maximum unit price in cents. 5000 means $50.00."
},
"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."
},
"description": {
"type": [
"string",
"null"
],
"description": "Plain-text listing copy. HTML and citation markers are removed."
},
"image_url": {
"type": [
"string",
"null"
],
"description": "Absolute https URL of the primary photo, or null when the listing has none."
},
"url": {
"type": "string",
"description": "Absolute URL of the public listing page."
},
"moq": {
"type": "integer"
},
"quote_threshold": {
"type": "integer"
},
"shipping_price": {
"type": [
"number",
"string"
],
"description": "Per-unit shipping as a number, or the string quote shipping."
},
"ship_from_country": {
"type": [
"string",
"null"
]
},
"instant_checkout_eligible": {
"type": "boolean"
},
"requires_verified_reseller": {
"type": "boolean"
},
"next_step": {
"type": "string"
},
"supplier": {
"type": "object",
"description": "Present when this listing's seller has claimed a published supplier profile.",
"properties": {
"name": {
"type": "string"
},
"slug": {
"type": "string"
},
"country": {
"type": "string"
},
"type": {
"type": "string"
},
"url": {
"type": "string"
}
},
"required": [
"name",
"slug",
"country",
"type",
"url"
]
}
},
"required": [
"id",
"name",
"category",
"quantity",
"price",
"url"
]
}
},
"total": {
"type": "integer",
"description": "Catalogue matches before the limit is applied."
},
"message": {
"type": "string"
}
},
"required": [
"products",
"total",
"message"
]
}🟢get_product_details(product_id, productId, id, slug)
Read one listing: description, price, quantity, condition, photo, and whether instant checkout is available. No sign-in required. Use this before requesting a quote or buying. Pass the exact id from search, for example product_2731.
입력 스키마
{
"type": "object",
"properties": {
"product_id": {
"type": "string",
"description": "Exact id from search, for example product_2731. productId, id, and slug are aliases."
},
"productId": {
"type": "string",
"description": "Alias for product_id."
},
"id": {
"type": "string",
"description": "Alias for product_id."
},
"slug": {
"type": "string",
"description": "Alias for product_id. Public listing slug, such as surplus-lot-2731."
}
}
}출력 스키마
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": [
"string",
"null"
],
"description": "Plain-text listing copy. HTML and citation markers are removed."
},
"image_url": {
"type": [
"string",
"null"
],
"description": "Absolute https URL of the primary photo, or null when the listing has none."
},
"url": {
"type": "string",
"description": "Absolute URL of the public listing page."
},
"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 only when the cached Stripe account can take charges and payouts. A mapped account that cannot charge is false. This is not the viewer's sign-in state."
}
},
"required": [
"company",
"verified"
]
},
"supplier": {
"type": "object",
"description": "Present when this listing's seller has claimed a published supplier profile.",
"properties": {
"name": {
"type": "string"
},
"slug": {
"type": "string"
},
"country": {
"type": "string"
},
"type": {
"type": "string"
},
"url": {
"type": "string"
}
},
"required": [
"name",
"slug",
"country",
"type",
"url"
]
},
"quote_required": {
"type": "boolean",
"description": "True when this listing has no quantity that can be paid directly. It is not 'the lot has more than 100 units'. Orders at or above quote_quantity_threshold still need a quote even when this is false. The charge path still confirms the seller can take a card."
},
"shipping_price_cents": {
"type": [
"integer",
"null"
],
"description": "Per-unit freight in cents, or null when not priced."
},
"shipping_method": {
"type": "string"
},
"lot_type": {
"type": "string"
},
"min_order_quantity": {
"type": "integer"
},
"ship_from": {
"type": [
"string",
"null"
]
},
"condition_definition": {
"type": "string"
},
"sold_as_is": {
"type": "boolean"
},
"claims_summary": {
"type": "string"
},
"claims_policy_url": {
"type": "string"
},
"terms_url": {
"type": "string"
},
"moq": {
"type": "integer"
},
"quote_threshold": {
"type": "integer"
},
"shipping_price": {
"type": [
"number",
"string"
],
"description": "Per-unit shipping as a number, or the string quote shipping."
},
"ship_from_country": {
"type": [
"string",
"null"
]
},
"instant_checkout_eligible": {
"type": "boolean"
},
"requires_verified_reseller": {
"type": "boolean"
},
"next_step": {
"type": "string"
},
"bulk_price_tiers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"min_quantity": {
"type": "integer"
},
"price_cents": {
"type": "integer"
}
},
"required": [
"min_quantity",
"price_cents"
]
}
}
},
"required": [
"id",
"name",
"category",
"quantity_available",
"price",
"quote_required",
"url"
]
}🟡request_quote(product_id, productId, id, slug, quantity, ...)
Ask a seller to price a bulk order. No sign-in required if you pass buyer_email, which is where the seller replies. buyer_email is always required, including when you are signed in. Anonymous requests are limited to 5 per hour. Sign in with buyer access to attach the quote to your account. Save status_token and pass it to get_quote_status. This does not charge a card. Sensitive: requires user approval each time.
입력 스키마
{
"type": "object",
"properties": {
"product_id": {
"type": "string",
"description": "Exact id from search, for example product_2731. productId, id, and slug are aliases."
},
"productId": {
"type": "string",
"description": "Alias for product_id."
},
"id": {
"type": "string",
"description": "Alias for product_id."
},
"slug": {
"type": "string",
"description": "Alias for product_id. Public listing slug."
},
"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"
},
"idempotency_key": {
"type": "string",
"description": "Required. 8–200 characters (letters, digits, . _ : -). The same key returns the original result for 24 hours and is sent to Stripe as Idempotency-Key."
}
},
"required": [
"product_id",
"quantity",
"buyer_email",
"idempotency_key"
]
}출력 스키마
{
"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": "What happens next. The seller is notified. There is no guaranteed reply time."
},
"seller_company": {
"type": "string"
}
},
"required": [
"id",
"product_id",
"product_name",
"quantity",
"status",
"expected_response"
]
},
"status_token": {
"type": "string",
"description": "Pass to get_quote_status to read this quote back. Keep it: an anonymous caller has no other way in."
}
},
"required": [
"success",
"message",
"quote"
]
}🟢get_quote_status(quote_id, status_token)
Check a quote you requested: pending, responded, accepted, rejected, or completed, plus the seller price and shipping once they reply. No sign-in required when you pass the status_token from request_quote. Signed-in buyers can also read their own quotes without the token.
입력 스키마
{
"type": "object",
"properties": {
"quote_id": {
"type": "integer",
"description": "Quote id from request_quote"
},
"status_token": {
"type": "string",
"description": "status_token from the request_quote response"
}
},
"required": [
"quote_id"
]
}출력 스키마
{
"type": "object",
"properties": {
"quote_id": {
"type": "integer"
},
"product_id": {
"type": "string"
},
"quantity": {
"type": "integer"
},
"status": {
"type": "string"
},
"target_price_per_unit": {
"type": [
"number",
"null"
]
},
"seller_response": {
"type": [
"object",
"null"
],
"properties": {
"price_per_unit": {
"type": "number"
},
"currency": {
"type": "string"
},
"shipping": {
"type": [
"number",
"null"
]
},
"total_additional_costs": {
"type": [
"number",
"null"
]
},
"message": {
"type": [
"string",
"null"
]
}
},
"required": [
"price_per_unit",
"currency"
]
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"next_action": {
"type": "string"
},
"buyer_quote_url": {
"type": "string"
}
},
"required": [
"quote_id",
"product_id",
"quantity",
"status",
"seller_response",
"created_at",
"updated_at",
"next_action",
"buyer_quote_url"
]
}🟡create_listing(name, description, category, condition, quantity, ...)
Publish a surplus lot for sale. Requires sign-in with seller access. Provide a title, category, condition, quantity, and price per unit. OAuth discovery: /.well-known/oauth-authorization-server (scope seller:write). Sensitive: requires user approval each time.
입력 스키마
{
"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": "Condition of the goods: salvage (sold as-is), customer returns, shelf pulls, overstock, or new or refurbished."
},
"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."
},
"idempotency_key": {
"type": "string",
"description": "Required. 8–200 characters (letters, digits, . _ : -). The same key returns the original result for 24 hours and is sent to Stripe as Idempotency-Key."
}
},
"required": [
"name",
"category",
"condition",
"quantity",
"price_per_unit",
"idempotency_key"
]
}출력 스키마
{
"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_pricing_recommendation(category, condition, original_retail, quantity)
Suggest a liquidation unit price in cents from MSRP, condition, category, and lot size. No sign-in required. original_retail is MSRP per unit in cents. Larger lots suggest a lower per-unit price. The result is bounded below retail. This does not change any listing's price.
입력 스키마
{
"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": "Condition of the goods: salvage (sold as-is), customer returns, shelf pulls, overstock, or new or refurbished."
},
"original_retail": {
"type": "integer",
"description": "MSRP per unit in cents. 5000 means $50.00. Required, and must be greater than zero."
},
"quantity": {
"type": "integer",
"description": "Units in the lot. Larger lots get a lower per-unit suggestion. Omit for a small lot."
}
},
"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_quote_requests(status)
List quote requests buyers sent you. Requires sign-in with seller access. Filter to pending, responded, or all. OAuth discovery: /.well-known/oauth-authorization-server (scope seller:read).
입력 스키마
{
"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_quote(quote_request_id, action, counter_price, message)
Answer a quote from a buyer by accepting it, sending a counter-price, or declining. Requires sign-in with seller access. The buyer is notified. OAuth discovery: /.well-known/oauth-authorization-server (scope seller:write). Sensitive: requires user approval each time.
입력 스키마
{
"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"
]
}출력 스키마
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
},
"quote": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"status": {
"type": "string"
},
"action": {
"type": "string"
},
"response_price": {
"type": "integer"
}
},
"required": [
"id",
"status",
"action"
]
}
},
"required": [
"success",
"message",
"quote"
]
}🔴bulk_update_listings(product_ids, mode, price_cents, value_usd, value)
Change the price or the minimum order quantity on up to 200 of your listings. Requires sign-in with seller access. price_set takes price_cents (integer cents). value_usd is an explicit dollar amount and is deprecated. The percent modes adjust the current price, and moq_set writes a minimum order quantity. Previous values are replaced. OAuth discovery: /.well-known/oauth-authorization-server (scope seller:write). Sensitive: requires user approval each time.
입력 스키마
{
"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 unit price in cents via price_cents, price_percent_increase / price_percent_decrease adjust the current price by a percentage, moq_set writes a minimum order quantity."
},
"price_cents": {
"type": "integer",
"description": "For price_set only. Absolute unit price in cents. 5000 means $50.00."
},
"value_usd": {
"type": "number",
"description": "Deprecated. For price_set only, an explicit price in US dollars. Prefer price_cents."
},
"value": {
"type": "number",
"description": "Percent (0-1000) for percent modes, or integer units (1-999999) for moq_set. Not accepted for price_set."
}
},
"required": [
"product_ids",
"mode"
]
}출력 스키마
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"mode": {
"type": "string"
},
"updated_count": {
"type": "integer"
},
"updates": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"before": {
"type": [
"number",
"null"
]
},
"after": {
"type": "number"
}
},
"required": [
"id",
"before",
"after"
]
}
},
"message": {
"type": "string"
}
},
"required": [
"success",
"mode",
"updated_count",
"updates",
"message"
]
}🔴set_listing_shipping(product_ids, shipping_price_cents, quote_shipping, lot_type, ship_from_country, ...)
Set how your listings ship: the shipping price per unit, or that shipping is quoted per order, and the lot type (parcel, pallet, truckload or mixed). Optionally set where your stock ships from; that is part of your seller account and shows on all your listings. Requires sign-in with seller access. Up to 200 of your listings per call; every id must be yours or nothing changes. shipping_price_cents is charged per unit at checkout (0 means free shipping). quote_shipping=true removes the fixed price so buyers ask for a quote, and turns off instant checkout on those listings, because instant checkout needs a fixed shipping price. OAuth discovery: /.well-known/oauth-authorization-server (scope seller:write). Sensitive: requires user approval each time.
입력 스키마
{
"type": "object",
"properties": {
"product_ids": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
},
"minItems": 1,
"maxItems": 200,
"description": "Your ForthClear product ids (max 200 per call)."
},
"shipping_price_cents": {
"type": "integer",
"minimum": 0,
"maximum": 10000000,
"description": "Shipping price per unit in cents, charged per unit at checkout. 0 means free shipping. Not with quote_shipping."
},
"quote_shipping": {
"type": "boolean",
"description": "true: no fixed shipping price; buyers request a quote that includes shipping. Turns off instant checkout on these listings. Not with shipping_price_cents."
},
"lot_type": {
"type": "string",
"enum": [
"parcel",
"pallet",
"truckload",
"mixed"
],
"description": "How the lot ships: parcel (boxes by courier), pallet, truckload, or mixed."
},
"ship_from_country": {
"type": "string",
"description": "Two-letter country code your stock ships from, for example US. Applies to your whole seller account."
},
"ship_from_region": {
"type": "string",
"description": "Optional state or region your stock ships from, for example Michigan. Applies to your whole seller account. Only with ship_from_country."
}
},
"required": [
"product_ids"
]
}출력 스키마
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"updated_count": {
"type": "integer"
},
"updates": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"shipping_price_cents": {
"type": [
"integer",
"null"
]
},
"lot_type": {
"type": "string"
}
},
"required": [
"id",
"shipping_price_cents",
"lot_type"
]
}
},
"ship_from": {
"type": [
"object",
"null"
],
"properties": {
"country": {
"type": "string"
},
"region": {
"type": [
"string",
"null"
]
}
}
},
"instant_checkout_turned_off": {
"type": "array",
"items": {
"type": "integer"
}
},
"message": {
"type": "string"
}
},
"required": [
"success",
"updated_count",
"updates",
"ship_from",
"instant_checkout_turned_off",
"message"
]
}🔴bulk_mark_shipped(order_ids, tracking_number, tracking_url, carrier_name)
Mark up to 200 of your orders as shipped, with an optional tracking number, tracking link, and carrier applied to the whole batch. Requires sign-in with seller access. Tracking you supply replaces tracking already on those orders, and each buyer is notified. OAuth discovery: /.well-known/oauth-authorization-server (scope seller:write). Sensitive: requires user approval each time.
입력 스키마
{
"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"
]
}출력 스키마
{
"type": "object",
"properties": {
"successful": {
"type": "array",
"items": {
"type": "integer"
}
},
"failed": {
"type": "array",
"items": {
"type": "object",
"properties": {
"orderId": {
"type": "integer"
},
"reason": {
"type": "string"
}
},
"required": [
"orderId",
"reason"
]
}
},
"successCount": {
"type": "integer"
},
"failureCount": {
"type": "integer"
},
"carrier": {
"type": [
"string",
"null"
]
}
},
"required": [
"successful",
"failed",
"successCount",
"failureCount",
"carrier"
]
}🟢bulk_export_orders(order_ids)
Download your orders as CSV, with order id, product, buyer, quantity, total, status, and date. Requires sign-in with seller access. Only orders you own are included. OAuth discovery: /.well-known/oauth-authorization-server (scope seller:read).
입력 스키마
{
"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"
]
}출력 스키마
{
"type": "object",
"properties": {
"filename": {
"type": "string"
},
"content_type": {
"type": "string"
},
"included_count": {
"type": "integer"
},
"requested_count": {
"type": "integer"
},
"skipped_count": {
"type": "integer"
},
"csv": {
"type": "string"
}
},
"required": [
"filename",
"content_type",
"included_count",
"requested_count",
"skipped_count",
"csv"
]
}🟢seller_inbox_summarise(window_hours, limit)
Summarise your seller inbox: quotes waiting for a reply, orders that may miss their ship-by date, and orders with reported problems. Requires sign-in with seller access. Use it to decide what to answer or ship next. OAuth discovery: /.well-known/oauth-authorization-server (scope seller:read).
입력 스키마
{
"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."
}
}
}출력 스키마
{
"type": "object",
"properties": {
"window_hours": {
"type": "integer"
},
"generated_at": {
"type": "string"
},
"counts": {
"type": "object",
"properties": {
"pending_quotes": {
"type": "integer"
},
"at_risk_orders": {
"type": "integer"
},
"reported_issues": {
"type": "integer"
}
},
"required": [
"pending_quotes",
"at_risk_orders",
"reported_issues"
]
},
"pending_quotes": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"product_id": {
"type": [
"string",
"null"
]
},
"buyer_id": {
"type": "integer"
},
"quantity": {
"type": "integer"
},
"target_price_cents": {
"type": [
"number",
"null"
]
},
"created_at": {
"type": "string"
}
},
"required": [
"id",
"quantity"
]
}
},
"at_risk_orders": {
"type": "array",
"items": {
"type": "object",
"properties": {
"order_id": {
"type": "integer"
},
"buyer_id": {
"type": "integer"
},
"ship_by": {
"type": "string"
},
"hours_remaining": {
"type": [
"number",
"null"
]
},
"status": {
"type": "string"
}
},
"required": [
"order_id",
"status"
]
}
},
"reported_issues": {
"type": "array",
"items": {
"type": "object",
"properties": {
"order_id": {
"type": "integer"
},
"buyer_id": {
"type": "integer"
},
"reported_at": {
"type": [
"string",
"null"
]
},
"status": {
"type": "string"
}
},
"required": [
"order_id",
"status"
]
}
},
"next_actions": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"window_hours",
"generated_at",
"counts",
"pending_quotes",
"at_risk_orders",
"reported_issues",
"next_actions"
]
}🔴quick_buy(product_id, productId, id, slug, quantity, ...)
Price an instant checkout for one listing. This does not charge the card. When the signed-in buyer has a saved card and the total is under US$1,000, the result is a summary (items, shipping, total, seller) plus a confirmation_token. Call confirm_purchase with that token and payment.saved_card true to charge the saved card. If there is no saved card, or the card needs authentication (including charges of US$1,000 or more), the result includes the existing checkout link instead. The listing's seller sells the goods. ForthClear runs the marketplace and Stripe processes the payment. buyer_email is required. quantity must be a positive integer below the listing's quote threshold (quote_quantity_threshold from get_product_details). A threshold of 1 means no quantity can be bought instantly. Use request_quote. The listing must have instant checkout and a shipping price. Requires sign-in with buyer access. OAuth discovery: /.well-known/oauth-authorization-server (scope buyer:purchase). Sensitive: requires user approval each time.
입력 스키마
{
"type": "object",
"properties": {
"product_id": {
"type": "string",
"description": "Exact id from search, for example product_2731. productId, id, and slug are aliases."
},
"productId": {
"type": "string",
"description": "Alias for product_id."
},
"id": {
"type": "string",
"description": "Alias for product_id."
},
"slug": {
"type": "string",
"description": "Alias for product_id. Public listing slug."
},
"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"
},
"idempotency_key": {
"type": "string",
"description": "Required. 8–200 characters (letters, digits, . _ : -). The same key returns the original result for 24 hours and is sent to Stripe as Idempotency-Key."
}
},
"required": [
"product_id",
"quantity",
"buyer_email",
"idempotency_key"
]
}출력 스키마
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
},
"checkout": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"status": {
"type": "string"
},
"product_name": {
"type": "string"
},
"quantity": {
"type": "integer"
},
"unit_price": {
"type": "integer"
},
"subtotal": {
"type": "integer"
},
"platform_fee": {
"type": "integer"
},
"grand_total": {
"type": "integer"
},
"currency": {
"type": "string"
},
"seller_of_record": {
"type": "string"
},
"shipping": {
"type": "integer"
},
"is_test": {
"type": "boolean"
},
"confirmation_token": {
"type": "string"
}
},
"required": [
"id",
"status",
"quantity",
"grand_total"
]
},
"payment": {
"type": "object",
"properties": {
"method": {
"type": "string"
},
"complete_url": {
"type": "string"
},
"instructions": {
"type": "string"
},
"contact_url": {
"type": "string"
},
"requires_confirmation": {
"type": "boolean"
},
"next_tool": {
"type": "string"
},
"checkout_id": {
"type": "string"
},
"confirmation_token": {
"type": "string"
},
"add_card_url": {
"type": "string"
}
},
"required": [
"method",
"instructions"
]
},
"next_steps": {
"type": "array",
"items": {
"type": "string"
}
},
"seller_of_record": {
"type": "string"
},
"confirmation_token": {
"type": "string"
},
"shipping_cents": {
"type": "integer"
},
"total_cents": {
"type": "integer"
},
"is_test": {
"type": "boolean"
},
"fallback_reason": {
"type": "string"
},
"add_card_url": {
"type": "string"
},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"product_id": {
"type": "string"
},
"name": {
"type": "string"
},
"quantity": {
"type": "integer"
},
"unit_price_cents": {
"type": "integer"
}
},
"required": [
"product_id",
"quantity",
"unit_price_cents"
]
}
}
},
"required": [
"success",
"checkout",
"payment",
"next_steps"
]
}🟢search_inventory_semantic(query, q, category, condition, max_price, ...)
Find listings by describing what you want in everyday language, such as returned kitchen appliances in bulk. No sign-in required. Semantic matches include similarity from 0 to 1 and match_type semantic. When the embedding index is empty or no provider is configured, results use keyword search, similarity is null, and match_type is keyword_fallback. category, when set, is one catalogue category such as electronics. max_price is the maximum unit price in cents.
입력 스키마
{
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Natural-language description of what the buyer wants. `q` is accepted as an alias."
},
"q": {
"type": "string",
"description": "Alias for query."
},
"category": {
"type": "string",
"enum": [
"electronics",
"apparel",
"home_goods",
"beauty",
"sports",
"kitchenware",
"office_supplies",
"toys",
"food_beverage",
"tools",
"other"
],
"description": "Limit to one 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": "Condition of the goods: salvage (sold as-is), customer returns, shelf pulls, overstock, or new or refurbished."
},
"max_price": {
"type": "integer",
"description": "Maximum price per unit in cents"
},
"limit": {
"type": "integer",
"default": 10,
"maximum": 50,
"description": "Number of ranked results to return"
}
},
"required": [
"query"
]
}출력 스키마
{
"type": "object",
"properties": {
"query": {
"type": "string"
},
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"product_id": {
"type": "integer"
},
"name": {
"type": "string"
},
"description": {
"type": [
"string",
"null"
]
},
"category": {
"type": [
"string",
"null"
]
},
"condition": {
"type": [
"string",
"null"
]
},
"quantity": {
"type": "integer"
},
"price": {
"type": "integer"
},
"original_retail": {
"type": [
"number",
"null"
]
},
"discount_percent": {
"type": [
"number",
"null"
]
},
"sku": {
"type": [
"string",
"null"
]
},
"image_url": {
"type": [
"string",
"null"
]
},
"url": {
"type": "string"
},
"similarity": {
"type": [
"number",
"null"
]
},
"match_type": {
"type": "string"
}
},
"required": [
"id",
"product_id",
"name",
"price",
"url",
"similarity",
"match_type"
]
}
},
"count": {
"type": "integer"
},
"model": {
"type": "string"
},
"message": {
"type": "string"
},
"total": {
"type": "integer"
},
"products": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": [
"string",
"null"
]
},
"category": {
"type": [
"string",
"null"
]
},
"condition": {
"type": [
"string",
"null"
]
},
"quantity": {
"type": "integer"
},
"price": {
"type": "integer"
},
"discount_percent": {
"type": [
"number",
"null"
]
},
"image_url": {
"type": [
"string",
"null"
]
},
"url": {
"type": "string"
},
"similarity": {
"type": [
"number",
"null"
]
},
"match_type": {
"type": "string"
}
},
"required": [
"id",
"name",
"price",
"url"
]
}
}
},
"required": [
"query",
"results",
"count",
"model",
"message",
"products",
"total"
]
}🟢get_order_status(order_id)
Check status, tracking, and the inspection deadline for an order you placed. Requires sign-in with buyer access. OAuth discovery: /.well-known/oauth-authorization-server (scope buyer:read).
입력 스키마
{
"type": "object",
"properties": {
"order_id": {
"type": "integer",
"description": "ForthClear order id"
}
},
"required": [
"order_id"
]
}출력 스키마
{
"type": "object",
"properties": {
"order_id": {
"type": "integer"
},
"status": {
"type": "string"
},
"quantity": {
"type": "integer"
},
"total_amount": {
"type": [
"number",
"null"
]
},
"currency": {
"type": "string"
},
"tracking": {
"type": [
"object",
"null"
],
"properties": {
"number": {
"type": "string"
},
"carrier": {
"type": [
"string",
"null"
]
},
"url": {
"type": [
"string",
"null"
]
},
"expected_delivery": {
"type": [
"string",
"null"
]
}
},
"required": [
"number"
]
},
"inspection_deadline": {
"type": [
"string",
"null"
]
},
"delivery_received_at": {
"type": [
"string",
"null"
]
},
"payment_released": {
"type": "boolean"
},
"issue_reported_at": {
"type": [
"string",
"null"
]
},
"ship_by_date": {
"type": [
"string",
"null"
]
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"next_actions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"description": {
"type": "string"
},
"deadline": {
"type": [
"string",
"null"
]
}
},
"required": [
"type",
"description"
]
}
}
},
"required": [
"order_id",
"status",
"quantity",
"currency",
"tracking",
"created_at",
"updated_at",
"next_actions"
]
}🔴open_dispute(order_id, reason, description, requested_action, photo_urls, ...)
Report a problem with an order. not_received is allowed while the order is marked shipped. Other reasons require a delivered order waiting for confirmation. This records the issue, pauses the seller payout, and notifies ForthClear. Requires sign-in with buyer access. OAuth discovery: /.well-known/oauth-authorization-server (scope buyer:write). Sensitive: requires user approval each time.
입력 스키마
{
"type": "object",
"properties": {
"order_id": {
"type": "integer",
"description": "ForthClear order id"
},
"reason": {
"type": "string",
"enum": [
"missing_units",
"quality_issue",
"damaged",
"wrong_item",
"not_received",
"other"
],
"description": "Dispute reason. not_received is allowed while the order is shipped. The other reasons require delivered_pending_confirmation."
},
"description": {
"type": "string",
"maxLength": 2000,
"description": "Free-text description of the issue"
},
"requested_action": {
"type": "string",
"enum": [
"refund",
"replacement",
"partial_refund"
],
"description": "Resolution the buyer is requesting"
},
"photo_urls": {
"type": "array",
"items": {
"type": "string",
"format": "uri"
},
"maxItems": 10,
"description": "Optional evidence URLs"
},
"idempotency_key": {
"type": "string",
"description": "Required. 8–200 characters (letters, digits, . _ : -). The same key returns the original result for 24 hours and is sent to Stripe as Idempotency-Key."
}
},
"required": [
"order_id",
"reason",
"description",
"idempotency_key"
]
}출력 스키마
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
},
"dispute_id": {
"type": "string"
},
"order_id": {
"type": "integer"
},
"status": {
"type": "string"
},
"opened_at": {
"type": "string"
},
"sla": {
"type": "object",
"properties": {
"admin_review_within_hours": {
"type": "integer"
},
"admin_review_deadline": {
"type": "string"
}
},
"required": [
"admin_review_within_hours",
"admin_review_deadline"
]
},
"next_actions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"description": {
"type": "string"
}
},
"required": [
"type",
"description"
]
}
}
},
"required": [
"success",
"message",
"dispute_id",
"order_id",
"status",
"opened_at",
"sla",
"next_actions"
]
}🟡subscribe_to_query(query, channels)
Save a catalogue search and receive new matching listings by email, webhook, or a pollable feed. Requires sign-in with buyer access. OAuth discovery: /.well-known/oauth-authorization-server (scope buyer:write).
입력 스키마
{
"type": "object",
"properties": {
"query": {
"type": "object",
"description": "Marketplace filter. Prices are US dollars per unit. Omit a field to leave it unset.",
"additionalProperties": false,
"properties": {
"search": {
"type": "string",
"maxLength": 200,
"description": "Words to match in the listing name, description, brand, or SKU."
},
"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."
},
"minPrice": {
"type": "number",
"minimum": 0,
"description": "Minimum unit price in US dollars. 50 means $50."
},
"maxPrice": {
"type": "number",
"minimum": 0,
"description": "Maximum unit price in US dollars. 50 means $50."
},
"minQuantity": {
"type": "integer",
"minimum": 0,
"description": "Minimum units available on the listing."
},
"bulkDealsOnly": {
"type": "boolean",
"description": "When true, only listings that have a bulk price tier."
},
"sellerCountry": {
"type": "string",
"maxLength": 10,
"description": "Seller country, as stored on the seller account (name or 2-letter code)."
},
"condition": {
"type": "string",
"enum": [
"salvage",
"customer_returns",
"shelf_pulls",
"overstock",
"new_or_refurbished"
],
"description": "Condition of the goods: salvage (sold as-is), customer returns, shelf pulls, overstock, or new or refurbished."
},
"moqRange": {
"type": "string",
"enum": [
"0",
"1-50",
"51-100",
"101-500",
"501-1000",
"1001+"
],
"description": "Minimum-order band: 0, 1-50, 51-100, 101-500, 501-1000, or 1001+."
},
"sort": {
"type": "string",
"enum": [
"newest",
"price_low",
"price_high",
"quantity_low",
"quantity_high",
"discount_desc",
"lot_total_low",
"lot_total_high"
],
"description": "Result order: newest, price_low, price_high, quantity_low, quantity_high, discount_desc, lot_total_low, or lot_total_high."
}
}
},
"channels": {
"type": "array",
"description": "Where to send new matches. One to five entries. Each entry is a webhook (public https URL), an email address, or mcp_resource (poll the returned feed).",
"minItems": 1,
"maxItems": 5,
"items": {
"oneOf": [
{
"type": "object",
"properties": {
"type": {
"const": "webhook",
"description": "Deliver matches by HTTP POST to url."
},
"url": {
"type": "string",
"format": "uri",
"description": "Public https URL that receives new matches. Private and loopback addresses are rejected."
}
},
"required": [
"type",
"url"
]
},
{
"type": "object",
"properties": {
"type": {
"const": "email",
"description": "Deliver matches by email."
},
"email": {
"type": "string",
"format": "email",
"description": "Address that receives new matches."
}
},
"required": [
"type",
"email"
]
},
{
"type": "object",
"properties": {
"type": {
"const": "mcp_resource",
"description": "Keep matches on a pollable feed. The response includes poll_url."
}
},
"required": [
"type"
]
}
]
}
}
},
"required": [
"query",
"channels"
]
}출력 스키마
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"subscription": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"query": {
"type": "object"
},
"channels": {
"type": "array",
"items": {
"type": "object"
}
},
"active": {
"type": "boolean"
},
"created_at": {
"type": "string"
},
"poll_url": {
"type": "string"
},
"unsubscribe_url": {
"type": "string"
}
},
"required": [
"id",
"query",
"channels",
"active",
"created_at",
"poll_url",
"unsubscribe_url"
]
},
"webhook_contract": {
"type": "object",
"properties": {
"event": {
"type": "string"
},
"signature_header": {
"type": "string"
},
"algorithm": {
"type": "string"
},
"encoding": {
"type": "string"
},
"secret_env": {
"type": "string"
}
},
"required": [
"event",
"signature_header",
"algorithm",
"encoding",
"secret_env"
]
}
},
"required": [
"success",
"subscription",
"webhook_contract"
]
}🟢search_suppliers(query, q, country, type, category, ...)
Search the supplier directory. No sign-in required. Returns published company profiles only, including profiles a company has claimed. These are not lots for sale. A profile is compiled from public sources and is not an endorsement. Use search_inventory to find lots you can buy. Filter with query, country, type (3pl, returns_processor, brand_retailer, liquidator, other), or category.
입력 스키마
{
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Words to match against the company name, city, or summary. `q` is accepted as an alias."
},
"q": {
"type": "string",
"description": "Alias for query."
},
"country": {
"type": "string",
"description": "Country name or 2-letter code, matched exactly."
},
"type": {
"type": "string",
"enum": [
"3pl",
"returns_processor",
"brand_retailer",
"liquidator",
"other"
],
"description": "Kind of company."
},
"category": {
"type": "string",
"description": "One category the profile lists, such as apparel or electronics."
},
"limit": {
"type": "integer",
"default": 20,
"maximum": 50,
"description": "Maximum profiles to return (default 20, max 50)."
}
}
}출력 스키마
{
"type": "object",
"properties": {
"suppliers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"slug": {
"type": "string"
},
"country": {
"type": "string"
},
"city": {
"type": [
"string",
"null"
]
},
"type": {
"type": "string"
},
"type_label": {
"type": "string"
},
"categories": {
"type": "array",
"items": {
"type": "string"
}
},
"blurb": {
"type": [
"string",
"null"
]
},
"website": {
"type": [
"string",
"null"
]
},
"claimed": {
"type": "boolean"
},
"url": {
"type": "string"
}
},
"required": [
"name",
"slug",
"country",
"type",
"categories",
"claimed",
"url"
]
}
},
"total": {
"type": "integer"
},
"message": {
"type": "string"
}
},
"required": [
"suppliers",
"total",
"message"
]
}🟢preview_checkout(product_id, productId, id, slug, quantity, ...)
Read the seller of record, unit price, shipping, tax, and total for an instant-checkout listing. Does not charge a card. Requires buyer read access. Pass the returned checkout_id to confirm_purchase. Requires sign-in with buyer access. OAuth discovery: /.well-known/oauth-authorization-server (scope buyer:read).
입력 스키마
{
"type": "object",
"properties": {
"product_id": {
"type": "string",
"description": "Exact id from search, for example product_2731. productId, id, and slug are aliases."
},
"productId": {
"type": "string",
"description": "Alias for product_id."
},
"id": {
"type": "string",
"description": "Alias for product_id."
},
"slug": {
"type": "string",
"description": "Alias for product_id. Public listing slug."
},
"quantity": {
"type": "integer",
"description": "Units to buy. Must be below the quote threshold."
},
"shipping_address_id": {
"type": "string",
"description": "Optional. Shipping is the listing's shipping price; tax is not collected on this path."
},
"idempotency_key": {
"type": "string",
"description": "Required. 8–200 characters (letters, digits, . _ : -). The same key returns the original result for 24 hours and is sent to Stripe as Idempotency-Key."
}
},
"required": [
"product_id",
"quantity",
"idempotency_key"
]
}출력 스키마
{
"type": "object",
"properties": {
"status": {
"type": "string"
},
"preview_id": {
"type": "string"
},
"checkout_id": {
"type": "string"
},
"expires_at": {
"type": "string"
},
"seller_of_record": {
"type": "string"
},
"currency": {
"type": "string"
},
"product_id": {
"type": "string"
},
"product_name": {
"type": "string"
},
"quantity": {
"type": "integer"
},
"unit_price_cents": {
"type": "integer"
},
"subtotal_cents": {
"type": "integer"
},
"shipping_cents": {
"type": "integer"
},
"tax_cents": {
"type": [
"integer",
"null"
]
},
"tax": {
"type": "string"
},
"buyer_fee_cents": {
"type": "integer"
},
"total_cents": {
"type": "integer"
},
"seller_fee_percent": {
"type": "integer"
},
"claims_summary": {
"type": "string",
"description": "Inspection is 3 days after the buyer marks the order received. Short-unit claims apply beyond a 5% tolerance. Salvage is as-is. Not-received claims are allowed while the order is shipped."
},
"claims_policy_url": {
"type": "string"
},
"terms_url": {
"type": "string"
},
"is_test": {
"type": "boolean"
},
"confirmation_token": {
"type": "string"
}
},
"required": [
"status",
"checkout_id",
"total_cents",
"seller_of_record"
]
}🔴confirm_purchase(checkout_id, confirmation_token, payment, idempotency_key)
Charge the previewed checkout with the signed-in buyer's own saved card, off session, or with a Stripe shared payment token when the SDK supports it. Pass confirmation_token from quick_buy or preview_checkout. A token or total that does not match the summary is rejected and nothing is charged. The same idempotency key does not create a second charge. Charges of US$1,000 or more, and cards that need authentication, return requires_action plus a checkout link. Returns confirmed only after the PaymentIntent succeeds and the order exists. Requires sign-in with buyer access. OAuth discovery: /.well-known/oauth-authorization-server (scope buyer:purchase). Sensitive: requires user approval each time.
입력 스키마
{
"type": "object",
"properties": {
"checkout_id": {
"type": "string",
"description": "checkout_id from quick_buy or preview_checkout."
},
"confirmation_token": {
"type": "string",
"description": "confirmation_token from the summary. Must match that checkout. A mismatch is rejected."
},
"payment": {
"type": "object",
"description": "shared_payment_token when the Stripe SDK supports it, or saved_card true.",
"properties": {
"shared_payment_token": {
"type": "string",
"description": "Stripe shared payment token."
},
"saved_card": {
"type": "boolean",
"description": "Charge the card saved on the ForthClear account."
}
}
},
"idempotency_key": {
"type": "string",
"description": "Required. 8–200 characters (letters, digits, . _ : -). The same key returns the original result for 24 hours and is sent to Stripe as Idempotency-Key."
}
},
"required": [
"checkout_id",
"payment",
"idempotency_key"
]
}출력 스키마
{
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "quoted, pending, requires_action, confirmed, failed, or cancelled."
},
"order_id": {
"type": [
"integer",
"null"
]
},
"checkout_id": {
"type": "string"
},
"amount_charged_cents": {
"type": [
"integer",
"null"
]
},
"currency": {
"type": "string"
},
"is_test": {
"type": "boolean"
},
"action_url": {
"type": [
"string",
"null"
]
},
"fallback_url": {
"type": [
"string",
"null"
]
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
}
},
"required": [
"status",
"checkout_id"
]
}🟢get_saved_card
Read whether the signed-in buyer has a card saved for in-chat checkout, and return the page where they can add one. Does not charge the card. Card numbers are not returned. Requires buyer read access. Requires sign-in with buyer access. OAuth discovery: /.well-known/oauth-authorization-server (scope buyer:read).
입력 스키마
{
"type": "object",
"properties": {}
}출력 스키마
{
"type": "object",
"properties": {
"saved": {
"type": "boolean"
},
"brand": {
"type": [
"string",
"null"
]
},
"last4": {
"type": [
"string",
"null"
]
},
"sandbox": {
"type": "boolean"
},
"add_card_url": {
"type": "string"
}
},
"required": [
"saved",
"add_card_url",
"sandbox"
]
}🟢list_my_orders(limit)
List orders the signed-in buyer placed. Requires buyer read access. Requires sign-in with buyer access. OAuth discovery: /.well-known/oauth-authorization-server (scope buyer:read).
입력 스키마
{
"type": "object",
"properties": {
"limit": {
"type": "integer",
"description": "Maximum orders to return, 1–50. Default 20."
}
}
}출력 스키마
{
"type": "object",
"properties": {
"orders": {
"type": "array",
"items": {
"type": "object",
"properties": {
"order_id": {
"type": "integer"
},
"role": {
"type": "string"
},
"product_id": {
"type": "string"
},
"quantity": {
"type": "integer"
},
"status": {
"type": "string"
},
"total_cents": {
"type": [
"integer",
"null"
]
},
"currency": {
"type": "string"
},
"tracking_number": {
"type": [
"string",
"null"
]
},
"ship_by": {
"type": [
"string",
"null"
]
},
"inspection_deadline": {
"type": [
"string",
"null"
]
},
"is_test": {
"type": "boolean"
},
"created_at": {
"type": [
"string",
"null"
]
}
},
"required": [
"order_id",
"status"
]
}
},
"total": {
"type": "integer"
}
},
"required": [
"orders",
"total"
]
}🟢list_seller_orders(limit)
List orders for the signed-in seller. Requires seller read access. Returns order id, status, quantity, and total. Buyer contact details stay on the order page. Requires sign-in with seller access. OAuth discovery: /.well-known/oauth-authorization-server (scope seller:read).
입력 스키마
{
"type": "object",
"properties": {
"limit": {
"type": "integer",
"description": "Maximum orders to return, 1–50. Default 20."
}
}
}출력 스키마
{
"type": "object",
"properties": {
"orders": {
"type": "array",
"items": {
"type": "object",
"properties": {
"order_id": {
"type": "integer"
},
"role": {
"type": "string"
},
"product_id": {
"type": "string"
},
"quantity": {
"type": "integer"
},
"status": {
"type": "string"
},
"total_cents": {
"type": [
"integer",
"null"
]
},
"currency": {
"type": "string"
},
"tracking_number": {
"type": [
"string",
"null"
]
},
"ship_by": {
"type": [
"string",
"null"
]
},
"inspection_deadline": {
"type": [
"string",
"null"
]
},
"is_test": {
"type": "boolean"
},
"created_at": {
"type": [
"string",
"null"
]
}
},
"required": [
"order_id",
"status"
]
}
},
"total": {
"type": "integer"
}
},
"required": [
"orders",
"total"
]
}🔴cancel_order(order_id, idempotency_key)
Cancel an unshipped order whose ship-by date has passed, for a full refund. Seller Agreement §5.4. Requires buyer purchase access. Requires sign-in with buyer access. OAuth discovery: /.well-known/oauth-authorization-server (scope buyer:purchase). Sensitive: requires user approval each time.
입력 스키마
{
"type": "object",
"properties": {
"order_id": {
"type": "integer",
"description": "ForthClear order id."
},
"idempotency_key": {
"type": "string",
"description": "Required. 8–200 characters (letters, digits, . _ : -). The same key returns the original result for 24 hours and is sent to Stripe as Idempotency-Key."
}
},
"required": [
"order_id",
"idempotency_key"
]
}출력 스키마
{
"type": "object",
"properties": {
"status": {
"type": "string"
},
"order_id": {
"type": "integer"
},
"refund": {
"type": "string"
},
"is_test": {
"type": "boolean"
}
},
"required": [
"status",
"order_id"
]
}🔴mark_order_received(order_id, idempotency_key)
Mark a shipped order received. This starts the 3-day inspection window and does not pay the seller. Requires buyer write access. Requires sign-in with buyer access. OAuth discovery: /.well-known/oauth-authorization-server (scope buyer:write).
입력 스키마
{
"type": "object",
"properties": {
"order_id": {
"type": "integer",
"description": "ForthClear order id."
},
"idempotency_key": {
"type": "string",
"description": "Required. 8–200 characters (letters, digits, . _ : -). The same key returns the original result for 24 hours and is sent to Stripe as Idempotency-Key."
}
},
"required": [
"order_id",
"idempotency_key"
]
}출력 스키마
{
"type": "object",
"properties": {
"order_id": {
"type": "integer"
},
"status": {
"type": "string"
},
"inspection_deadline": {
"type": [
"string",
"null"
]
}
},
"required": [
"order_id",
"status"
]
}🔴confirm_order(order_id, idempotency_key)
End the inspection window after it has elapsed. A live order then starts the seller payout. A sandbox order is marked delivered and is not paid out. Requires buyer write access. Requires sign-in with buyer access. OAuth discovery: /.well-known/oauth-authorization-server (scope buyer:write).
입력 스키마
{
"type": "object",
"properties": {
"order_id": {
"type": "integer",
"description": "ForthClear order id."
},
"idempotency_key": {
"type": "string",
"description": "Required. 8–200 characters (letters, digits, . _ : -). The same key returns the original result for 24 hours and is sent to Stripe as Idempotency-Key."
}
},
"required": [
"order_id",
"idempotency_key"
]
}출력 스키마
{
"type": "object",
"properties": {
"order_id": {
"type": "integer"
},
"status": {
"type": "string"
},
"payout": {
"type": "string"
}
},
"required": [
"order_id",
"status"
]
}🟢get_dispute_status(order_id)
Read the claim on an order you placed. Requires buyer read access. Requires sign-in with buyer access. OAuth discovery: /.well-known/oauth-authorization-server (scope buyer:read).
입력 스키마
{
"type": "object",
"properties": {
"order_id": {
"type": "integer",
"description": "ForthClear order id."
}
},
"required": [
"order_id"
]
}출력 스키마
{
"type": "object",
"properties": {
"order_id": {
"type": "integer"
},
"order_status": {
"type": "string"
},
"claim_status": {
"type": [
"string",
"null"
]
},
"payout_paused": {
"type": "boolean"
},
"reason": {
"type": [
"string",
"null"
]
},
"description": {
"type": [
"string",
"null"
]
},
"reported_at": {
"type": [
"string",
"null"
]
}
},
"required": [
"order_id",
"order_status"
]
}🟢list_my_quotes(limit)
List quote requests for the signed-in buyer. Requires buyer read access. Requires sign-in with buyer access. OAuth discovery: /.well-known/oauth-authorization-server (scope buyer:read).
입력 스키마
{
"type": "object",
"properties": {
"limit": {
"type": "integer",
"description": "Maximum quotes to return, 1-50. Default 20."
}
}
}출력 스키마
{
"type": "object",
"properties": {
"quotes": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"product_id": {
"type": "string"
},
"quantity": {
"type": "integer"
},
"status": {
"type": "string"
},
"target_price_cents": {
"type": [
"integer",
"null"
]
},
"response_price_cents": {
"type": [
"integer",
"null"
]
},
"created_at": {
"type": [
"string",
"null"
]
}
},
"required": [
"id",
"status"
]
}
},
"total": {
"type": "integer"
}
},
"required": [
"quotes",
"total"
]
}🔴accept_quote_and_pay(quote_id, payment, idempotency_key)
Accept a seller's quoted price and charge it with the same payment options as confirm_purchase. Requires buyer purchase access. Requires sign-in with buyer access. OAuth discovery: /.well-known/oauth-authorization-server (scope buyer:purchase). Sensitive: requires user approval each time.
입력 스키마
{
"type": "object",
"properties": {
"quote_id": {
"type": "integer",
"description": "Quote id from list_my_quotes or get_quote_status."
},
"payment": {
"type": "object",
"description": "Same payment object as confirm_purchase.",
"properties": {
"shared_payment_token": {
"type": "string",
"description": "Stripe shared payment token."
},
"saved_card": {
"type": "boolean",
"description": "Charge the saved card."
}
}
},
"idempotency_key": {
"type": "string",
"description": "Required. 8–200 characters (letters, digits, . _ : -). The same key returns the original result for 24 hours and is sent to Stripe as Idempotency-Key."
}
},
"required": [
"quote_id",
"payment",
"idempotency_key"
]
}출력 스키마
{
"type": "object",
"properties": {
"status": {
"type": "string"
},
"order_id": {
"type": [
"integer",
"null"
]
},
"checkout_id": {
"type": "string"
},
"amount_charged_cents": {
"type": [
"integer",
"null"
]
},
"currency": {
"type": "string"
},
"is_test": {
"type": "boolean"
},
"action_url": {
"type": [
"string",
"null"
]
}
},
"required": [
"status"
]
}커뮤니티
증거