Orders
Orders, line items, returns and tracking.
/ordersCursor-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
| 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 | Marketplace channel. One of: "tiktok", "ebay", "etsy", "amazon" |
shopId | query | string | 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 | query | string | Channel-neutral order state. One of: "AWAITING_PAYMENT", "AWAITING_SHIPMENT", "SHIPPED", "DELIVERED", "COMPLETED", "CANCELLED", "RETURN_REQUESTED", "REFUNDED" |
fulfillmentStatus | query | string | POD fulfilment state, independent of the marketplace order state. One of: "UNFULFILLED", "QUEUED", "SENT_TO_SUPPLIER", "IN_PRODUCTION", "FULFILLED", "FAILED" |
search | query | string | Free-text match on marketplace order id, the marketplace's own order number ( |
searchIn | query | string | Narrows One of: "all", "product", "order", "buyer", "tracking" |
placedFrom | query | string (date-time) | string (date) | Lower bound on placedAt, inclusive. |
placedTo | query | string (date-time) | string (date) | Upper bound on placedAt, inclusive. |
updatedSince | query | string (date-time) | string (date) | Only orders updated at or after this instant. Use for incremental sync. |
sortBy | query | string | Sort key. Pair One of: "placedAt", "updatedAt" default "placedAt" |
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/orders' \
-H "Authorization: Bearer $DOCTORX_API_KEY"/orders/status-countsDistribution 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
| 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 | Marketplace channel. One of: "tiktok", "ebay", "etsy", "amazon" |
shopId | query | string | 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 | query | string | Channel-neutral order state. One of: "AWAITING_PAYMENT", "AWAITING_SHIPMENT", "SHIPPED", "DELIVERED", "COMPLETED", "CANCELLED", "RETURN_REQUESTED", "REFUNDED" |
fulfillmentStatus | query | string | POD fulfilment state, independent of the marketplace order state. One of: "UNFULFILLED", "QUEUED", "SENT_TO_SUPPLIER", "IN_PRODUCTION", "FULFILLED", "FAILED" |
search | query | string | Free-text match on marketplace order id, the marketplace's own order number ( |
searchIn | query | string | Narrows One of: "all", "product", "order", "buyer", "tracking" |
placedFrom | query | string (date-time) | string (date) | Lower bound on placedAt, inclusive. |
placedTo | query | string (date-time) | string (date) | Upper bound on placedAt, inclusive. |
updatedSince | query | string (date-time) | string (date) | Only orders updated at or after this instant. Use for incremental sync. |
sortBy | query | string | Sort key. Pair One of: "placedAt", "updatedAt" default "placedAt" |
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/orders/status-counts' \
-H "Authorization: Bearer $DOCTORX_API_KEY"/orders/returnsReturns 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
| 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 | Marketplace channel. One of: "tiktok", "ebay", "etsy", "amazon" |
shopId | query | string | 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 | query | string | 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 | query | string | Exact match on the channel's own status wording ( |
updatedSince | query | string (date-time) | string (date) | Only returns whose CHANNEL update time is at or after this instant. Use for incremental sync. |
sortBy | query | string | Sort key. Pair One of: "returnUpdatedAt", "returnCreatedAt" default "returnUpdatedAt" |
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/orders/returns' \
-H "Authorization: Bearer $DOCTORX_API_KEY"/orders/exportThe 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
| Name | In | Type | Description |
|---|---|---|---|
order | query | string | Sort direction on the collection sort key. One of: "asc", "desc" default "desc" |
channel | query | string | Marketplace channel. One of: "tiktok", "ebay", "etsy", "amazon" |
shopId | query | string | 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 | query | string | Channel-neutral order state. One of: "AWAITING_PAYMENT", "AWAITING_SHIPMENT", "SHIPPED", "DELIVERED", "COMPLETED", "CANCELLED", "RETURN_REQUESTED", "REFUNDED" |
fulfillmentStatus | query | string | POD fulfilment state, independent of the marketplace order state. One of: "UNFULFILLED", "QUEUED", "SENT_TO_SUPPLIER", "IN_PRODUCTION", "FULFILLED", "FAILED" |
search | query | string | Free-text match on marketplace order id, the marketplace's own order number ( |
searchIn | query | string | Narrows One of: "all", "product", "order", "buyer", "tracking" |
placedFrom | query | string (date-time) | string (date) | Lower bound on placedAt, inclusive. |
placedTo | query | string (date-time) | string (date) | Upper bound on placedAt, inclusive. |
updatedSince | query | string (date-time) | string (date) | Only orders updated at or after this instant. Use for incremental sync. |
sortBy | query | string | Sort key. Pair One of: "placedAt", "updatedAt" default "placedAt" |
withLabels | query | string | 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
| 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/orders/export' \
-H "Authorization: Bearer $DOCTORX_API_KEY"/orders/mark-exportedSets 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[]requiredOrders to stamp. Ids outside your tenant are ignored.
min items 1 · max items 10000
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/orders/mark-exported' \
-H "Authorization: Bearer $DOCTORX_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"orderIds": [
"string"
]
}'/orders/{id}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
| 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/orders/string' \
-H "Authorization: Bearer $DOCTORX_API_KEY"/orders/{id}/shipping-providersThe 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
| 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/orders/string/shipping-providers' \
-H "Authorization: Bearer $DOCTORX_API_KEY"/orders/{id}/historyEtsy 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
| 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/orders/string/history' \
-H "Authorization: Bearer $DOCTORX_API_KEY"/orders/{id}/cancelCancels 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
| 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/orders/string/cancel' \
-H "Authorization: Bearer $DOCTORX_API_KEY" \
-H "Idempotency-Key: $(uuidgen)"/orders/tracking/bulkUp 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
| 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/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
}
]
}'/orders/{id}/trackingPrefer 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
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Request body
numberstringrequiredmin length 1 · max length 200
carrierstringFree-text carrier name.
max length 200
shippingProviderIdstringChannel provider id from GET /orders/{id}/shipping-providers. Preferred over carrier.
max length 200
fulfillmentOrderIdintegerEtsy 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
| 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/orders/string/tracking' \
-H "Authorization: Bearer $DOCTORX_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"number": "string"
}'/orders/sync/{shopId}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
| Name | In | Type | Description |
|---|---|---|---|
shopIdrequired | path | string |
Request body (optional)
backfillDaysintegerPull 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
| 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/orders/sync/string' \
-H "Authorization: Bearer $DOCTORX_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{}'