DoctorX logoDoctorX Get an API key

Changes (polling)

Incremental sync feeds for partners without webhooks.

Incremental product sync. Pass updatedSince on the first call, then follow meta.pagination.nextCursor until hasMore is false; persist the last cursor and resume from it next time. Always walks ascending by updatedAt, so a row updated mid-walk is still delivered. A change appears here once it is two minutes old, and resuming from your cursor never skips one. For anything more urgent, use webhooks.

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

Marketplace channel.

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

status
querystring

DoctorX-side listing lifecycle state.

One of: "draft", "ready", "live", "error", "archived"

source
querystring

How the listing entered DoctorX. pulled mirrors a listing that already exists on the marketplace and can never be re-published over.

One of: "template", "pod", "pulled", "csv", "crawlbot"

templateId
querystring

DoctorX resource id: a UUID in canonical 8-4-4-4-12 hex form. Version and variant bits are not constrained.

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}$

shopId
querystring

Only products carrying a shop-sync on this shop.

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}$

syncStatus
querystring

Narrow the shopId match to a specific push state, e.g. synced for live listings only.

One of: "pending", "syncing", "synced", "failed"

drxSku
querystring

Exact match on the seller design SKU.

search
querystring

Free-text match on title, category, template name, seller SKU, tags, and the variant SKUs, and on the name, code and search terms of the template the product is bound to: each word may match the product or its template, so a title word and a template code together find it. A channel name or listing-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 products updated at or after this instant. Pair it with sortBy=updatedAt for an incremental walk, which is what /changes/products 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.

One of: "createdAt", "updatedAt"

default "createdAt"

Responses

200ProductListResponse
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/changes/products' \
  -H "Authorization: Bearer $DOCTORX_API_KEY"

Incremental order sync, same cursor contract as /changes/products. Covers created, updated, status-changed, cancelled and tracking changes in one stream, since all of them touch updatedAt. It ALSO covers a settlement reconcile, which rewrites the fee fields without any seller action. A change appears here once it is two minutes old, and resuming from your cursor never skips one. For anything more urgent, use webhooks.

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

Marketplace channel.

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

shopId
querystring

DoctorX resource id: a UUID in canonical 8-4-4-4-12 hex form. Version and variant bits are not constrained.

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}$

status
querystring

Channel-neutral order state.

One of: "AWAITING_PAYMENT", "AWAITING_SHIPMENT", "SHIPPED", "DELIVERED", "COMPLETED", "CANCELLED", "RETURN_REQUESTED", "REFUNDED"

fulfillmentStatus
querystring

POD fulfilment state, independent of the marketplace order state.

One of: "UNFULFILLED", "QUEUED", "SENT_TO_SUPPLIER", "IN_PRODUCTION", "FULFILLED", "FAILED"

search
querystring

Free-text match on marketplace order id, the marketplace's own order number (channelOrderNo: the Etsy receipt id, the Amazon order number), shop name, tracking number and carrier, notes, supplier reference, and the order lines (title, SKU, variant, channel product id). An order-status or fulfillment-status word in English or Vietnamese matches that status. BUYER NAME, EMAIL, PHONE, HANDLE AND STREET ADDRESS are matched only when the key holds orders:pii; without that scope those fields are excluded from the match and the other fields still match, because a search result is itself a disclosure and a key that may not read a phone number must not be able to confirm one by searching for it. 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.

searchIn
querystring

Narrows search to one part of the order. product: the order lines (title, SKU, variant, channel product id). order: the marketplace order id and the marketplace's own order number (channelOrderNo), or the record id. buyer: buyer name, email, phone, handle and shipping address; needs orders:pii, and a key without it is refused with 403. tracking: tracking number and carrier. all, or no value, searches the whole order.

One of: "all", "product", "order", "buyer", "tracking"

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

Lower bound on placedAt, inclusive.

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

Upper bound on placedAt, inclusive.

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

Only orders updated at or after this instant. Use for incremental sync.

sortBy
querystring

Sort key. Pair updatedAt with updatedSince for incremental pulls.

One of: "placedAt", "updatedAt"

default "placedAt"

Responses

200OrderListResponse
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/changes/orders' \
  -H "Authorization: Bearer $DOCTORX_API_KEY"

Incremental return sync. This is the feed the return lifecycle had NO equivalent of: order.return_created fires once, and a return changing state does not touch its order's updatedAt, so /changes/orders could not see it either. Walks ascending by the CHANNEL's own update time. A change appears here once it is two minutes old, and resuming from your cursor never skips one. For anything more urgent, use webhooks.

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

Marketplace channel.

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

shopId
querystring

DoctorX resource id: a UUID in canonical 8-4-4-4-12 hex form. Version and variant bits are not constrained.

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}$

orderId
querystring

Only returns against this DoctorX order.

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}$

status
querystring

Exact match on the channel's own status wording (REFUND_SUCCESS, ...). Not a DoctorX enum: the vocabulary is the marketplace's and differs per channel.

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

Only returns whose CHANNEL update time is at or after this instant. Use for incremental sync.

sortBy
querystring

Sort key. Pair returnUpdatedAt with updatedSince.

One of: "returnUpdatedAt", "returnCreatedAt"

default "returnUpdatedAt"

Responses

200OrderReturnListResponse
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/changes/returns' \
  -H "Authorization: Bearer $DOCTORX_API_KEY"

Incremental template sync, same cursor contract as /changes/products. A template carries the category, policies and variation axes every product built from it inherits, so a partner mirroring the catalog has to follow it as well as the products. A change appears here once it is two minutes old, and resuming from your cursor never skips one. For anything more urgent, use webhooks.

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

Marketplace channel.

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

category
querystring
search
querystring

Free-text match on template name, seller template code and search terms, and on the category and title template of each of its channels (a term may mix the template text with one channel). A channel name in English or Vietnamese matches the channel. 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.

includeHidden
querystring
preset
querystring

Return the PRESET library instead: this tenant’s presets plus every GLOBAL preset.

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

Only templates changed at or after this instant. Pair it with sortBy=updatedAt for an incremental walk, which is what /changes/templates 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.

One of: "createdAt", "updatedAt"

default "createdAt"

Responses

200TemplateListResponse
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/changes/templates' \
  -H "Authorization: Bearer $DOCTORX_API_KEY"

Incremental sync of connection state. Covers a shop connecting, disconnecting, losing its grant, changing its listing restriction or moving its balance, all of which alter what a publish will do. The webhook equivalents (shop.*) cover only the first three. A change appears here once it is two minutes old, and resuming from your cursor never skips one. For anything more urgent, use webhooks.

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/changes/shops' \
  -H "Authorization: Bearer $DOCTORX_API_KEY"

Incremental Etsy and Amazon ledger sync, across the key's shops. Delivers every entry DoctorX records (including an Amazon transaction that arrives after its date) and every entry whose figures or status change afterwards (an Amazon transaction moving from DEFERRED to RELEASED), ascending by when DoctorX wrote it. Pass updatedSince on the first call, follow meta.pagination.nextCursor until hasMore is false, and keep the last cursor to resume. The ledger is read from the marketplace every 6 hours and on POST /finances/sync. A change appears here once it is two minutes old, and resuming from your cursor never skips one. For anything more urgent, use webhooks.

Parameters

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

Only entries DoctorX recorded or changed at or after this instant. Omitted: from the beginning.

shopId
querystring

Restrict to one shop.

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}$

channel
querystring

Marketplace channel.

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

limit
queryinteger

Entries per page, 1..200.

min 1 · max 200 · default 50

cursor
querystring

Opaque: pass back meta.pagination.nextCursor verbatim, and keep the last one to resume.

Responses

200LedgerEntryListResponse
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/changes/ledger-entries' \
  -H "Authorization: Bearer $DOCTORX_API_KEY"

Incremental payout sync. Keyed on when DoctorX last WROTE the row rather than on settledAt, because a statement is re-pulled and re-reconciled after it first lands: a feed keyed on the settlement date would never re-deliver a payout whose figures had since been corrected. A change appears here once it is two minutes old, and resuming from your cursor never skips one. For anything more urgent, use webhooks.

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

shopId
querystring

Restrict to one shop.

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}$

channel
querystring

Marketplace channel.

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

status
querystring

One of: "PAID", "PROCESSING"

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

Inclusive lower bound on settledAt.

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

Inclusive upper bound on settledAt.

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

Only payouts DoctorX wrote at or after this instant. Distinct from settledFrom, which filters on when the marketplace settled: a statement is re-pulled and re-reconciled after it first lands, so a feed keyed on the settlement date would never re-deliver a payout whose figures were later corrected.

sortBy
querystring

Sort key. Pair updatedAt with updatedSince.

One of: "settledAt", "updatedAt"

default "settledAt"

Responses

200PayoutListResponse
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/changes/payouts' \
  -H "Authorization: Bearer $DOCTORX_API_KEY"