Conventions
The rules every endpoint follows, so you can write them once.
Versioning
The version is part of every path (/v1, in the base URL). This reference describes document version 1.0.0.
Responses and errors
Success is always { "data": ..., "meta": ... }. Failure is always:
{
"error": {
"code": "product_not_found",
"message": "No such product for this tenant.",
"details": ["optional field-level or upstream detail"],
"requestId": "quote this when contacting support"
}
}Branch on code, never on message (messages are for humans and may be reworded).
| Code | HTTP | Meaning |
|---|---|---|
unauthorized | 401 | Missing or malformed API key. |
invalid_api_key | 401 | The API key is unknown. |
api_key_revoked | 401 | The API key has been revoked. |
api_key_expired | 401 | The API key has expired. |
scope_insufficient | 403 | The API key lacks the scope required for this operation. |
shop_not_permitted | 403 | The API key is not bound to this shop. |
subscription_suspended | 402 | The workspace subscription has lapsed and access is suspended. The account owner must renew the plan; no change to this API key will restore access. If the workspace stays suspended for 7 days, its business data is deleted. |
feature_required | 403 | The tenant plan does not include this feature. |
plan_upgrade_required | 402 | The workspace plan is below the pack this API requires. The account owner must upgrade the plan; no change to this API key will restore access. |
validation_failed | 400 | The request payload failed validation. |
invalid_cursor | 400 | The pagination cursor is malformed or expired. |
idempotency_key_reused | 409 | This Idempotency-Key was used with a different request body. |
idempotency_in_progress | 409 | A request with this Idempotency-Key is still in flight. |
unsupported_media_type | 415 | Request bodies must be application/json. |
shop_not_found | 404 | No such shop for this tenant. |
template_not_found | 404 | No such template for this tenant. |
product_not_found | 404 | No such product for this tenant. |
order_not_found | 404 | No such order for this tenant. |
ledger_entry_not_found | 404 | No such ledger entry in this shop. |
webhook_endpoint_not_found | 404 | No such webhook endpoint for this tenant. |
webhook_delivery_not_found | 404 | No such webhook delivery for this tenant. |
etsy_profile_not_found | 404 | No such Etsy shipping profile, return policy, processing profile or shop section for this shop. |
endpoint_not_found | 404 | No such endpoint on this API version. |
resource_conflict | 409 | The resource already exists. |
channel_not_supported | 400 | This channel does not support the requested operation. |
template_required | 400 | The product needs a template that targets this channel before it can be published. |
invalid_category | 400 | The marketplace category is not a valid leaf for this shop, or its taxonomy version does not match. |
pulled_listing_not_publishable | 409 | This product mirrors a listing that already exists on the marketplace, so DoctorX refuses to overwrite it. To list a TikTok listing on another shop, make a DoctorX product from it in DoctorX first, then publish that product. |
shop_not_connected | 409 | The shop is not connected, or it is paused. Re-authorize a shop that is not connected; a paused shop is resumed from the DoctorX dashboard. |
publish_blocked | 409 | The publish was refused by a pre-flight check. |
order_action_refused | 409 | The order state does not allow this action. |
product_merged | 409 | This product was merged into another listing. Set its price, stock and variant photos on that listing; its cost and fulfil setup stay editable here. |
invalid_webhook_url | 400 | The webhook URL must be a public HTTPS address. |
channel_error | 422 | The marketplace rejected the request. |
channel_rate_limited | 429 | The marketplace is rate limiting us; retry shortly. |
channel_unavailable | 429 | The marketplace is temporarily unreachable; retry shortly. |
channel_auth_expired | 409 | The marketplace authorization expired or is invalid; re-authorize the shop. |
channel_scope_missing | 409 | The marketplace grant is missing the access scope this operation needs; the seller must re-consent. |
channel_setup_required | 409 | The marketplace account is not ready for this operation; the seller must complete setup on the marketplace. |
rate_limited | 429 | Rate limit exceeded for this API key. |
internal_error | 500 | An unexpected error occurred. |
Marketplace failures are mapped onto this catalog where the class is actionable
(channel_auth_expired means re-authorize the shop, channel_scope_missing means the
seller must re-consent, channel_rate_limited means back off). Anything else stays
channel_error with the marketplace's verbatim message in details, rather than
asserting a taxonomy the marketplace does not publish.
Pagination
Collections are cursor-paginated, not offset-paginated, so a concurrent insert can neither duplicate nor skip a row while you walk a large set.
GET /products?limit=100
-> meta.pagination = { limit, nextCursor, hasMore }
GET /products?limit=100&cursor=<nextCursor>Page size is 1..200, default 50. Treat nextCursor as
opaque and pass it back verbatim. Follow it until hasMore is false. meta.pagination.total
is only present when you ask for it with includeTotal=true, because counting a large
filtered set is the expensive half of the query and most callers do not need it.
Rate limits
Limits are per API key, counted in a fixed one-minute window:
- 600 read requests per minute (GET/HEAD)
- 120 write requests per minute (POST/PATCH/DELETE)
Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and
X-RateLimit-Reset (seconds until the window closes). On 429 a Retry-After
header tells you exactly how long to wait. Reads and writes have separate budgets because
a write can fan out to a marketplace API with its own quota.
Idempotency
Send Idempotency-Key: <your-unique-value> on any write. If you retry after a timeout,
the original response is replayed byte-for-byte instead of the operation running twice, and
the replay carries Idempotency-Replayed: true. Keys are remembered for 24 hours and are
scoped to the tenant and the endpoint. Reusing one key with a different body is a
client bug and is rejected with idempotency_key_reused.
Incremental sync
For a partner that keeps its own mirror, use the change feeds:
GET /changes/products?updatedSince=2026-07-01T00:00:00Z
GET /changes/orders?updatedSince=2026-07-01T00:00:00ZThey walk ascending by updatedAt over a keyset cursor, so a row updated DURING your
walk is still delivered rather than missed. Persist the last nextCursor and resume from
it. These are the recommended fallback when you cannot receive webhooks.
Channel differences
Marketplaces do not support the same operations. Call GET /authorize/channels first: a
false capability means the corresponding endpoint answers channel_not_supported instead
of failing deeper at the marketplace. Concretely, only TikTok supports a partial content
edit and a shipping label; only eBay reports a listing quota; Amazon cannot end a listing
through DoctorX.
Currency
Product prices and costs are always USD (they are seller-set and have no marketplace
currency). Order and shop amounts are in the shop's native marketplace currency, named
by the currency field beside them. Order COGS is the exception inside an order: it is
USD and says so via costCurrency. Never assume a currency from context, and never sum
across shops without converting.
