DoctorX logoDoctorX Get an API key

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).

CodeHTTPMeaning
unauthorized401Missing or malformed API key.
invalid_api_key401The API key is unknown.
api_key_revoked401The API key has been revoked.
api_key_expired401The API key has expired.
scope_insufficient403The API key lacks the scope required for this operation.
shop_not_permitted403The API key is not bound to this shop.
subscription_suspended402The 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_required403The tenant plan does not include this feature.
plan_upgrade_required402The 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_failed400The request payload failed validation.
invalid_cursor400The pagination cursor is malformed or expired.
idempotency_key_reused409This Idempotency-Key was used with a different request body.
idempotency_in_progress409A request with this Idempotency-Key is still in flight.
unsupported_media_type415Request bodies must be application/json.
shop_not_found404No such shop for this tenant.
template_not_found404No such template for this tenant.
product_not_found404No such product for this tenant.
order_not_found404No such order for this tenant.
ledger_entry_not_found404No such ledger entry in this shop.
webhook_endpoint_not_found404No such webhook endpoint for this tenant.
webhook_delivery_not_found404No such webhook delivery for this tenant.
etsy_profile_not_found404No such Etsy shipping profile, return policy, processing profile or shop section for this shop.
endpoint_not_found404No such endpoint on this API version.
resource_conflict409The resource already exists.
channel_not_supported400This channel does not support the requested operation.
template_required400The product needs a template that targets this channel before it can be published.
invalid_category400The marketplace category is not a valid leaf for this shop, or its taxonomy version does not match.
pulled_listing_not_publishable409This 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_connected409The 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_blocked409The publish was refused by a pre-flight check.
order_action_refused409The order state does not allow this action.
product_merged409This 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_url400The webhook URL must be a public HTTPS address.
channel_error422The marketplace rejected the request.
channel_rate_limited429The marketplace is rate limiting us; retry shortly.
channel_unavailable429The marketplace is temporarily unreachable; retry shortly.
channel_auth_expired409The marketplace authorization expired or is invalid; re-authorize the shop.
channel_scope_missing409The marketplace grant is missing the access scope this operation needs; the seller must re-consent.
channel_setup_required409The marketplace account is not ready for this operation; the seller must complete setup on the marketplace.
rate_limited429Rate limit exceeded for this API key.
internal_error500An 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:00Z

They 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.