Back

Supplier API

Connect your inventory and order systems directly — update prices, sync stock, and pull orders programmatically.

Getting started

Create an API key in your supplier dashboard under Settings → API keys. The key is shown exactly once — copy it immediately. Only a one-way hash is stored, so a lost key cannot be recovered; create a new one instead. Keys can be revoked at any time from the same page.

Authentication

Send your key on every request with either header:

Authorization: Bearer <your-api-key>
X-API-Key: <your-api-key>

Base URL: https://<your-store-domain>/api/v1

Never put the key in a URL. Requests without a valid key return 401 {"error":"invalid_api_key"}. Error messages are always in English and never localized — this is a machine interface.

Endpoints

GET/api/v1/products

List your own products: id, name, base price, stock and status.

# example
curl -H "Authorization: Bearer <key>" \
https://<domain>/api/v1/products

# response
{ "products": [{ "id": 42, "name": "Steel water bottle",
"price": 3.9, "stock": 1200, "status": "published" }] }

PATCH/api/v1/products/:id

Update the price and/or stock of one of your products. price must be a number greater than 0 and maps onto the base (first) price tier; stock_qty must be an integer of 0 or more. Send at least one of the two.

# example
curl -X PATCH -H "Authorization: Bearer <key>" \
-H "Content-Type: application/json" \
-d '{"price": 4.2, "stock_qty": 900}' \
https://<domain>/api/v1/products/42

GET/api/v1/orders

Orders that contain at least one of your items, newest first.

Parameter	Default	Rules
`limit`	20	integer, 1–100
`offset`	0	integer, ≥ 0

{ "orders": [{ "id": 7, "order_no": "CB-0007",
"status": "paid", "total": 420, "currency": "USD" }],
"pagination": { "limit": 20, "offset": 0, "total": 3 } }

GET/api/v1/orders/:id

One of your orders with its line items (product_id, title, qty, unit_price, is_sample).

Lead webhooks (CRM / ERP sync)

Suppliers configure a webhook URL in the supplier dashboard under Integrations (/supplier/integrations). On a new inquiry addressed to you, or a new RFQ where you are the invited supplier, the platform POSTs a signed JSON payload to your URL. Failed deliveries retry twice (after 1 minute, then 10 minutes) and then stop; every attempt is recorded in the delivery log on the same page.

POSTyour webhook URL

Headers: X-CB-Event: inquiry.created | rfq.created, X-CB-Signature: sha256=<HMAC-SHA256 hex of the raw JSON body, keyed by your webhook secret>, X-CB-Delivery: <delivery id>. Verify the signature before trusting the payload; reject anything that does not verify. Any 2xx response counts as delivered.

{ "event": "inquiry.created", "occurred_at": "2026-10-25T06:00:00.000Z",
"lead": { "type": "inquiry", "id": 123, "product_id": 42,
"product_name": "Steel water bottle", "category": "Kitchenware",
"quantity": 500, "is_sample": false, "topic": "pricing",
"supplier_city": "Rajkot", "supplier_country": "India" },
"buyer": { "company_type": "Importer", "country": "Germany" } }

For rfq.created the lead block carries type: "rfq", id, title, category, quantity, needed_by and the same buyer block.

Privacy, by design: webhook payloads never contain quoted or target prices, buyer or supplier names, company names, emails, phone numbers, exact addresses, or free-text messages — only listing info plus the buyer's company type and country. Open RFQs without an invited supplier are never pushed to anyone.

CRM / ERP connector mappings (stub)

Field mappings for Zoho CRM (Lead), HubSpot CRM (Contact + Deal), and Salesforce (Lead) are documented on the supplier Integrations page. They are stubs today: no keys are stored and no data is sent to any CRM. The mapped fields are exactly the safe lead fields above — lead.type, lead.id, lead.product_name, lead.category, lead.quantity, lead.is_sample, lead.topic, buyer.company_type, buyer.country, lead.supplier_country — so a future live connection cannot leak prices, contact details, or free text. A real provider connection is a launch step.

Agent APIs (AI shopping agents)

Besides the supplier REST API above, the platform exposes open agent-commerce interfaces — no supplier action needed:

ACP (Agentic Commerce Protocol): GET /.well-known/acp.json (discovery), GET /acp/feed (product feed), and ACP checkout sessions under /acp/checkout_sessions (stub payment provider — no real money).
UCP (Universal Commerce Protocol): GET /.well-known/ucp (discovery), catalog search/lookup under /.well-known/ucp/catalog/, agent RFQ submission at POST /.well-known/ucp/rfq/submit (buyer agent tokens, managed at /buyer/agent-tokens), and UCP checkout sessions under /.well-known/ucp/checkout-sessions (stub only).
All agent surfaces expose public listing prices only, supplier company name plus city/country only, and never RFQ/quotation prices, emails, phone numbers, or tax IDs.

Rate limits

120 requests per minute per key. Exceeding it returns 429 {"error":"rate_limited"} — back off and retry.

Errors

Status	`error` code	Meaning
401	`invalid_api_key`	Missing, revoked, or wrong key
404	`not_found`	Unknown endpoint, or product/order is not yours
422	`no_updates`	PATCH body contained neither price nor stock_qty
422	`invalid_price`	price must be a number > 0
422	`invalid_stock`	stock_qty must be an integer ≥ 0
422	`invalid_pagination`	limit/offset outside the allowed ranges
429	`rate_limited`	120 requests/minute exceeded

Good practice: store the key server-side as an environment variable, never in client-side code or a public repo. If a key leaks, revoke it in the dashboard and create a new one — revocation takes effect immediately.