DoctorX logoDoctorX Get an API key

Authorize

Connected shops, grant health, and channel capabilities.

GET/authorize/shops

Includes the marketplace shop id, the underlying grant status and token expiry, native-currency balances, and the live listing count (SYNCED pushes only, not attempts).

Parameters

NameInTypeDescription
limit
queryinteger

Page size, 1..200. Defaults to 50.

min 1 · max 200 · default 50

cursor
querystring

Opaque cursor from a previous response meta.pagination.nextCursor.

order
querystring

Sort direction on the collection sort key.

One of: "asc", "desc"

default "desc"

includeTotal
querystring

When true, meta.pagination.total carries the full matching count (an extra COUNT query).

channel
querystring

Filter to one channel.

One of: "tiktok", "ebay", "etsy", "amazon"

status
querystring

Filter to one authorization status.

One of: "connected", "expired", "revoked", "disconnected", "error", "paused"

search
querystring

Free-text match on shop name, custom name, shop code, channel shop id, region, market and currency. A channel or status word in English or Vietnamese matches that field. Whitespace is collapsed and the term is folded, so the match is case- and accent-insensitive (Dat matches Đạt). Every word must match: more words narrow the result, they do not widen it. A word of letters matches at the start of a word in the text (dad matches Dad and Daddy, not Trinidad); a word containing a digit matches anywhere, so the tail of an order, tracking or SKU number still finds it. Punctuation separates words (t-shirt matches T-Shirt and t shirt). Wrap words in double quotes to require them adjacent. % and _ are not wildcards: punctuation only separates words, so a term of punctuation alone matches nothing. A term that is a valid UUID also matches the record id exactly.

updatedSince
querystring (date-time) | string (date)

Only shops changed at or after this instant. Pair it with sortBy=updatedAt for an incremental walk, which is what /changes/shops does for you.

sortBy
querystring

Sort key. STATED rather than inferred from updatedSince, deliberately: a cursor is minted against a column, so an inferred key changes the moment a caller drops a filter and turns a resumed walk into invalid_cursor. Orders and payouts take an explicit key for the same reason.

One of: "connectedAt", "updatedAt"

default "connectedAt"

Responses

200ShopListResponse
StatusMeaning (body: error envelope)
400

Validation failed, or the request is not valid for this resource.

401

The API key is missing, unknown, revoked or expired.

403

The API key lacks the required scope, or is not bound to this shop.

404

No such resource for this tenant.

409

The request conflicts with the current state (see error.code).

422

The marketplace rejected the request; error.details carries its own message.

429

Back off and retry. error.code says whose limit was hit: rate_limited is ours (honour Retry-After), channel_rate_limited is the marketplace throttling us, channel_unavailable is the marketplace being unreachable.

500

A defect on our side (internal_error), and the only status left outside the 4xx range. The origin emits the envelope below, but the edge in front of api.doctorx.vn replaces the body of a 5xx with its own plain-text page, so do NOT require this body to parse: branch on the status.

Request sample

curl -X GET 'https://api.doctorx.vn/api/public/v1/authorize/shops' \
  -H "Authorization: Bearer $DOCTORX_API_KEY"
GET/authorize/shops/{id}

Parameters

NameInTypeDescription
idrequired
pathstring

Responses

200ShopResponse
StatusMeaning (body: error envelope)
400

Validation failed, or the request is not valid for this resource.

401

The API key is missing, unknown, revoked or expired.

403

The API key lacks the required scope, or is not bound to this shop.

404

No such resource for this tenant.

409

The request conflicts with the current state (see error.code).

422

The marketplace rejected the request; error.details carries its own message.

429

Back off and retry. error.code says whose limit was hit: rate_limited is ours (honour Retry-After), channel_rate_limited is the marketplace throttling us, channel_unavailable is the marketplace being unreachable.

500

A defect on our side (internal_error), and the only status left outside the 4xx range. The origin emits the envelope below, but the edge in front of api.doctorx.vn replaces the body of a 5xx with its own plain-text page, so do NOT require this body to parse: branch on the status.

Request sample

curl -X GET 'https://api.doctorx.vn/api/public/v1/authorize/shops/string' \
  -H "Authorization: Bearer $DOCTORX_API_KEY"
DELETE/authorize/shops/{id}

Removes the shop and its DoctorX-side references in one transaction. Live marketplace listings are NOT ended. Products DoctorX imported from the shop that nothing in DoctorX was built on (no orders, template, design SKU, cross-listing group or media edits) are removed shortly after it and announced as product.deleted (source: "shop_removed"); an imported product somebody worked on is kept, and gets its listing back if the shop is authorized again. So does every product built in DoctorX that the shop listed: authorized again, the shop gives each of its listings back to that product (its template and design SKU unchanged) instead of importing a second copy. A TikTok shop is not removed while some of its listings are still being updated after a recent publish: the response is disconnected: false with a message saying so, and nothing is changed. That usually settles within minutes, so repeat the call a few minutes later; 24 hours after the latest such publish, the call removes the shop regardless. A shop whose authorization is revoked or expired is removed regardless.

Parameters

NameInTypeDescription
idrequired
pathstring

Responses

200DisconnectResponse
StatusMeaning (body: error envelope)
400

Validation failed, or the request is not valid for this resource.

401

The API key is missing, unknown, revoked or expired.

403

The API key lacks the required scope, or is not bound to this shop.

404

No such resource for this tenant.

409

The request conflicts with the current state (see error.code).

422

The marketplace rejected the request; error.details carries its own message.

429

Back off and retry. error.code says whose limit was hit: rate_limited is ours (honour Retry-After), channel_rate_limited is the marketplace throttling us, channel_unavailable is the marketplace being unreachable.

500

A defect on our side (internal_error), and the only status left outside the 4xx range. The origin emits the envelope below, but the edge in front of api.doctorx.vn replaces the body of a 5xx with its own plain-text page, so do NOT require this body to parse: branch on the status.

Request sample

curl -X DELETE 'https://api.doctorx.vn/api/public/v1/authorize/shops/string' \
  -H "Authorization: Bearer $DOCTORX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
GET/authorize/shops/{id}/warehouses

The ids for channelMeta.tiktokWarehouseId. Bind externalId (the CHANNEL’s id), not id (ours): binding the wrong one produces a listing the channel refuses for an unknown warehouse. Rows are SYNCED from the channel, so an empty list usually means the shop has never been synced rather than that it has none. A return warehouse is not a fulfilment source and binding one is a configuration error the channel does not catch for you.

Parameters

NameInTypeDescription
idrequired
pathstring

Responses

200WarehouseListResponse
StatusMeaning (body: error envelope)
400

Validation failed, or the request is not valid for this resource.

401

The API key is missing, unknown, revoked or expired.

403

The API key lacks the required scope, or is not bound to this shop.

404

No such resource for this tenant.

409

The request conflicts with the current state (see error.code).

422

The marketplace rejected the request; error.details carries its own message.

429

Back off and retry. error.code says whose limit was hit: rate_limited is ours (honour Retry-After), channel_rate_limited is the marketplace throttling us, channel_unavailable is the marketplace being unreachable.

500

A defect on our side (internal_error), and the only status left outside the 4xx range. The origin emits the envelope below, but the edge in front of api.doctorx.vn replaces the body of a 5xx with its own plain-text page, so do NOT require this body to parse: branch on the status.

Request sample

curl -X GET 'https://api.doctorx.vn/api/public/v1/authorize/shops/string/warehouses' \
  -H "Authorization: Bearer $DOCTORX_API_KEY"
GET/authorize/channels

What each marketplace supports, declared by its adapter. Read this before calling an operation: a false capability means the endpoint answers channel_not_supported rather than failing at the marketplace. Also reports whether this tenant has a connected shop on the channel, and the channel’s hard title limit.

Responses

200ChannelCapabilityListResponse
StatusMeaning (body: error envelope)
400

Validation failed, or the request is not valid for this resource.

401

The API key is missing, unknown, revoked or expired.

403

The API key lacks the required scope, or is not bound to this shop.

404

No such resource for this tenant.

409

The request conflicts with the current state (see error.code).

422

The marketplace rejected the request; error.details carries its own message.

429

Back off and retry. error.code says whose limit was hit: rate_limited is ours (honour Retry-After), channel_rate_limited is the marketplace throttling us, channel_unavailable is the marketplace being unreachable.

500

A defect on our side (internal_error), and the only status left outside the 4xx range. The origin emits the envelope below, but the edge in front of api.doctorx.vn replaces the body of a 5xx with its own plain-text page, so do NOT require this body to parse: branch on the status.

Request sample

curl -X GET 'https://api.doctorx.vn/api/public/v1/authorize/channels' \
  -H "Authorization: Bearer $DOCTORX_API_KEY"
POST/authorize/connect

Returns a single-use authorization URL for the SELLER to open. usage: chat is TikTok only: TikTok approves customer service messaging as a separate app, and chat links it to US shops already connected via main (it adds no shop). On any other channel chat answers 400 channel_not_supported, because that channel's messaging runs on the shop's main authorization. usage: promotion is no longer accepted: the DoctorX TikTok app carries promotion scope itself, so a shop connected with main can run promotions with no second consent. Send shopId to re-authorize a connected TikTok Shop, eBay or Amazon shop instead (never remove a shop to renew it: removing deletes its orders and imported listings from DoctorX): the plan's shop limit is not checked again for a shop that already counts toward it, and only that shop changes. A key bound to specific shops cannot connect new ones, and may re-authorize its own shops.

Request body

channelstringrequired

Marketplace channel.

One of: "tiktok", "ebay", "etsy", "amazon"

usagestring

Which marketplace app to authorize. chat is TikTok only: TikTok approves customer service messaging as a separate app needing its own consent, and chat links it to US shops already connected via main (it adds no shop). Any other channel answers 400 for chat, because its messaging runs on the shop's main authorization. promotion was removed: the DoctorX TikTok app now carries promotion scope itself, so a newly connected shop can run promotions with no second consent.

One of: "main", "chat"

default "main"

marketstring

TikTok Shop market to authorize: US (default) or UK. TikTok registers each app to ONE market and refuses a seller from another market at its own consent page, so this must match the seller shop. It also decides which DoctorX app the seller consents to, and therefore what the resulting shop can do: US uses the DoctorX app that carries promotion scope, so the shop reads promoAppLinked: true immediately; UK uses the older app, which has no promotion scope, so a UK shop reads false and no call can change that. TikTok only: sending it for another channel is a 400. Omit to keep the existing default-market behaviour.

shopIdstring

Re-authorize this connected shop instead of connecting new ones: the seller signs in to the marketplace as this shop and consents again, and the shop keeps everything DoctorX holds for it. TikTok Shop, eBay and Amazon shops only (Etsy answers 400 channel_not_supported); usage must be main; the shop's own market is used, so omit market or send that market. The plan's shop limit is not checked again for a shop that already counts toward it (every status except revoked and disconnected); a revoked or disconnected shop needs room under the limit, as a new shop does. It changes only this shop: when the seller consents with a marketplace account that does not include this shop, nothing is connected or changed, and the shop's authorization stays as it was. A key bound to specific shops may re-authorize those shops. Poll GET /authorize/shops/{id} (or listen for shop.connected) for the outcome.

pattern ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

Responses

200StartConnectResponse
StatusMeaning (body: error envelope)
400

Validation failed, or the request is not valid for this resource.

401

The API key is missing, unknown, revoked or expired.

403

The API key lacks the required scope, or is not bound to this shop.

404

No such resource for this tenant.

409

The request conflicts with the current state (see error.code).

422

The marketplace rejected the request; error.details carries its own message.

429

Back off and retry. error.code says whose limit was hit: rate_limited is ours (honour Retry-After), channel_rate_limited is the marketplace throttling us, channel_unavailable is the marketplace being unreachable.

500

A defect on our side (internal_error), and the only status left outside the 4xx range. The origin emits the envelope below, but the edge in front of api.doctorx.vn replaces the body of a 5xx with its own plain-text page, so do NOT require this body to parse: branch on the status.

Request sample

curl -X POST 'https://api.doctorx.vn/api/public/v1/authorize/connect' \
  -H "Authorization: Bearer $DOCTORX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "channel": "tiktok"
}'
POST/authorize/shops/{id}/pull-catalog

Creates local mirrors of listings that already exist on the marketplace, so they can be managed from DoctorX. A mirror is never re-published over (that would overwrite the real listing), so publishing one is refused. Bounded by a page cap per run: re-run when the message says it was capped. Authorizing a shop already imports its listings in the background, and on TikTok and eBay a listing created on the marketplace afterwards (on eBay, also an item put up again, which gets a new item id) is imported on its own within about 30 minutes (only listings on sale, as here; no product.created event is sent for it, as for this call). While any of those imports (or another pull of the same shop) is running, this answers at once with pulled: 0 and a message saying the listings are already being imported, and they appear in GET /products as they arrive.

Parameters

NameInTypeDescription
idrequired
pathstring

Responses

200PullCatalogResponse
StatusMeaning (body: error envelope)
400

Validation failed, or the request is not valid for this resource.

401

The API key is missing, unknown, revoked or expired.

403

The API key lacks the required scope, or is not bound to this shop.

404

No such resource for this tenant.

409

The request conflicts with the current state (see error.code).

422

The marketplace rejected the request; error.details carries its own message.

429

Back off and retry. error.code says whose limit was hit: rate_limited is ours (honour Retry-After), channel_rate_limited is the marketplace throttling us, channel_unavailable is the marketplace being unreachable.

500

A defect on our side (internal_error), and the only status left outside the 4xx range. The origin emits the envelope below, but the edge in front of api.doctorx.vn replaces the body of a 5xx with its own plain-text page, so do NOT require this body to parse: branch on the status.

Request sample

curl -X POST 'https://api.doctorx.vn/api/public/v1/authorize/shops/string/pull-catalog' \
  -H "Authorization: Bearer $DOCTORX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"