DoctorX logoDoctorX Get an API key

Orders

Orders, line items, returns and tracking.

GET/orders

Cursor-paginated. For incremental sync pass updatedSince with sortBy=updatedAt, which walks a stable sequence even while orders are being updated. Returns and fulfilment are detail-only.

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/orders' \
  -H "Authorization: Bearer $DOCTORX_API_KEY"
GET/orders/status-counts

Distribution across statuses for the otherwise-filtered set. Every status key is present, including zeros. Declared before /{id} so the literal path is not read as an order id.

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

200OrderStatusCountsResponse
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/orders/status-counts' \
  -H "Authorization: Bearer $DOCTORX_API_KEY"
GET/orders/returns

Returns as their own collection, across every order. Previously reachable only as returns[] on an order detail, which meant finding a refund required re-reading every order. Sorted and filtered on the CHANNEL's own timestamps, so a re-pull that changed nothing does not re-deliver the row. Declared before /{id} so the literal path is not read as an order id.

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

The ENTIRE filtered set as a matrix, header row first, in the same column order the dashboard export produces, capped at 10,000 orders. Not paginated and not a file: a partner wants the rows, and a CSV would force them to parse one back. withLabels costs two marketplace calls per order and on TikTok it ARRANGES THE SHIPMENT, so leave it false unless the seller asked for label links. Declared before /{id} so the literal path is not read as an order id.

Parameters

NameInTypeDescription
order
querystring

Sort direction on the collection sort key.

One of: "asc", "desc"

default "desc"

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"

withLabels
querystring

Resolve a channel shipping label for every order that has none cached. This is TWO marketplace calls per order and, on TikTok, it ARRANGES THE SHIPMENT: a carrier is committed and a tracking number is minted, which cannot be undone. Leave it false unless the seller asked for label links.

Responses

200OrderExportResponse
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/orders/export' \
  -H "Authorization: Bearer $DOCTORX_API_KEY"
POST/orders/mark-exported

Sets exportedAt, the flag an operator uses to tell "already downloaded" from "new". Pass the orderIds the export returned. Without this a partner-run export leaves the dashboard believing those orders were never taken.

Request body

orderIdsstring[]required

Orders to stamp. Ids outside your tenant are ignored.

min items 1 · max items 10000

Responses

200MarkExportedResponse
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/orders/mark-exported' \
  -H "Authorization: Bearer $DOCTORX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "orderIds": [
    "string"
  ]
}'

Every line item, buyer block, recipient address, financial breakdown with its native currency, tax, discount, reconciled marketplace fee, tracking with carrier events, structured returns, and the submitted POD fulfilment (read-only). Buyer name, street and phone usually arrive already masked by the marketplace.

Parameters

NameInTypeDescription
idrequired
pathstring

Responses

200OrderResponse
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/orders/string' \
  -H "Authorization: Bearer $DOCTORX_API_KEY"
GET/orders/{id}/shipping-providers

The channel’s own provider list, for use as shippingProviderId when setting tracking. Empty when the shop is unmapped or the channel exposes no list, in which case send a free-text carrier.

Parameters

NameInTypeDescription
idrequired
pathstring

Responses

200ShippingProviderListResponse
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/orders/string/shipping-providers' \
  -H "Authorization: Bearer $DOCTORX_API_KEY"

Etsy and Amazon: every entry the marketplace connection recorded for this order, oldest first (created, then each update with the fields that changed and their old and new values), read live. Other channels answer channel_not_supported. Without orders:pii, a value that can identify the buyer is masked with dots.

Parameters

NameInTypeDescription
idrequired
pathstring

Responses

200OrderHistoryListResponse
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/orders/string/history' \
  -H "Authorization: Bearer $DOCTORX_API_KEY"
POST/orders/{id}/cancel

Cancels locally, cancels any POD fulfilment, then makes a best-effort marketplace cancel where the channel supports one (check capabilities.cancelOrder). A failed marketplace cancel never blocks the local one. Only an order awaiting payment or shipment can be cancelled.

Parameters

NameInTypeDescription
idrequired
pathstring

Responses

200OrderResponse
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/orders/string/cancel' \
  -H "Authorization: Bearer $DOCTORX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Up to 20 orders per request, each exactly as POST /orders/{id}/tracking takes it, run one after another; a refused row does not stop the others and carries its own error. Send an Idempotency-Key header: a retried request then answers what the first one did instead of pushing again. For more orders, send consecutive requests (see the partner guide for the measured pace).

Request body

Up to 20 orders, each exactly as POST /orders/{id}/tracking takes it. Rows run one after another; a refused row does not stop the others.

min items 1 · max items 20

Responses

200BulkTrackingResponse
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/orders/tracking/bulk' \
  -H "Authorization: Bearer $DOCTORX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "items": [
    {
      "orderId": "string",
      "number": "string",
      "carrier": "string",
      "shippingProviderId": "string",
      "fulfillmentOrderId": 0
    }
  ]
}'

Prefer shippingProviderId from /orders/{id}/shipping-providers so the channel push uses its own carrier id exactly; carrier is the free-text fallback. Idempotent: an order already pushed is not pushed twice.

Parameters

NameInTypeDescription
idrequired
pathstring

Request body

numberstringrequired

min length 1 · max length 200

carrierstring

Free-text carrier name.

max length 200

shippingProviderIdstring

Channel provider id from GET /orders/{id}/shipping-providers. Preferred over carrier.

max length 200

fulfillmentOrderIdinteger

Etsy and Amazon only: the parcel to attach the tracking to, from trackingPush.fulfillmentOrderIds after a push answered ambiguousParcel. Leave it out on a first push.

max 9007199254740991

Responses

200OrderResponse
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/orders/string/tracking' \
  -H "Authorization: Bearer $DOCTORX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "number": "string"
}'

Without a body this is an incremental pull from the last watermark (or the channel cold-start floor on a fresh shop: 90 days for TikTok and eBay, about ten years for Etsy and Amazon). With backfillDays it reaches a wide historical window WITHOUT moving the watermark, which is how order history older than the cold-start is recovered. Authorizing a shop (for the first time or again) already reads its order history in the background, the whole of it on a shop’s first authorization, so this is for a shop whose history you need again. TikTok and eBay are pulled inside the request (state: done). Etsy and Amazon are read page by page and can take minutes, so they are QUEUED on the same queue as the background sync and answered at once: queued, running (a sync is reading the shop now) or limited (one was requested in the last 5 minutes; retryAt says when to ask again). Follow the result in GET /changes/orders.

Parameters

NameInTypeDescription
shopIdrequired
pathstring

Request body (optional)

backfillDaysinteger

Pull a WIDE historical window this many days back WITHOUT moving the incremental watermark. Omit for a normal incremental pull. THIS IS ALSO THE REPAIR FOR ORDER LINES THAT NEVER LINKED TO A PRODUCT: a line resolves its product ONCE, at ingest, so orders that arrived before their catalogue was imported stay unlinked for ever and report no cost. Re-ingesting those orders through this call is what re-resolves the link; nothing recomputes it in place. eBay serves the last two years of orders only: on an eBay shop a longer window reads those two years, and message says so.

min 1 · max 3650

Responses

200OrderSyncResponse
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/orders/sync/string' \
  -H "Authorization: Bearer $DOCTORX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'