Authorize
Connected shops, grant health, and channel capabilities.
/authorize/shopsIncludes 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
| Name | In | Type | Description |
|---|---|---|---|
limit | query | integer | Page size, 1..200. Defaults to 50. min 1 · max 200 · default 50 |
cursor | query | string | Opaque cursor from a previous response meta.pagination.nextCursor. |
order | query | string | Sort direction on the collection sort key. One of: "asc", "desc" default "desc" |
includeTotal | query | string | When true, meta.pagination.total carries the full matching count (an extra COUNT query). |
channel | query | string | Filter to one channel. One of: "tiktok", "ebay", "etsy", "amazon" |
status | query | string | Filter to one authorization status. One of: "connected", "expired", "revoked", "disconnected", "error", "paused" |
search | query | string | 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 ( |
updatedSince | query | string (date-time) | string (date) | Only shops changed at or after this instant. Pair it with |
sortBy | query | string | Sort key. STATED rather than inferred from One of: "connectedAt", "updatedAt" default "connectedAt" |
Responses
| Status | Meaning (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 |
| 422 | The marketplace rejected the request; |
| 429 | Back off and retry. |
| 500 | A defect on our side ( |
Request sample
curl -X GET 'https://api.doctorx.vn/api/public/v1/authorize/shops' \
-H "Authorization: Bearer $DOCTORX_API_KEY"/authorize/shops/{id}Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Responses
| Status | Meaning (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 |
| 422 | The marketplace rejected the request; |
| 429 | Back off and retry. |
| 500 | A defect on our side ( |
Request sample
curl -X GET 'https://api.doctorx.vn/api/public/v1/authorize/shops/string' \
-H "Authorization: Bearer $DOCTORX_API_KEY"/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
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Responses
| Status | Meaning (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 |
| 422 | The marketplace rejected the request; |
| 429 | Back off and retry. |
| 500 | A defect on our side ( |
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)"/authorize/shops/{id}/warehousesThe 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
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Responses
| Status | Meaning (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 |
| 422 | The marketplace rejected the request; |
| 429 | Back off and retry. |
| 500 | A defect on our side ( |
Request sample
curl -X GET 'https://api.doctorx.vn/api/public/v1/authorize/shops/string/warehouses' \
-H "Authorization: Bearer $DOCTORX_API_KEY"/authorize/channelsWhat 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
| Status | Meaning (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 |
| 422 | The marketplace rejected the request; |
| 429 | Back off and retry. |
| 500 | A defect on our side ( |
Request sample
curl -X GET 'https://api.doctorx.vn/api/public/v1/authorize/channels' \
-H "Authorization: Bearer $DOCTORX_API_KEY"/authorize/connectReturns 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
channelstringrequiredMarketplace channel.
One of: "tiktok", "ebay", "etsy", "amazon"
usagestringWhich 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"
marketstringTikTok 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.
shopIdstringRe-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
| Status | Meaning (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 |
| 422 | The marketplace rejected the request; |
| 429 | Back off and retry. |
| 500 | A defect on our side ( |
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"
}'/authorize/shops/{id}/pull-catalogCreates 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
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Responses
| Status | Meaning (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 |
| 422 | The marketplace rejected the request; |
| 429 | Back off and retry. |
| 500 | A defect on our side ( |
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)"