DoctorX logoDoctorX Get an API key

Products

Products, variants, per-shop listings and publishing.

GET/products

Cursor-paginated. Pass updatedSince for incremental sync: the sort key switches to updatedAt so no row is missed between polls. templateAttributes is empty here and populated on the detail read.

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

The template supplies the marketplace category, variation axes and pricing grid, and must already target the requested channel. Variants are expanded from the template unless supplied explicitly.

Request body

titlestringrequired

min length 1 · max length 500

templateIdstringrequired

Template that carries the category, policies and variation axes.

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

channelstringrequired

Marketplace channel.

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

pricenumberrequired

min 0

descriptionstring

default ""

costnumber

Production cost for EVERY variant of this listing, USD, over what the template states. Omitted = each variant takes what its template says: its variantGrid row’s cost, else pricingRule.baseCost, else no cost on record (cost: 0 with costEstimated: true).

min 0

imagesstring (uri)[]

The listing’s OWN gallery image URLs; the first is its cover. A template’s fixedImages are published after these and are not part of this list. Bounded by the same constant the dashboard write path uses; a channel that publishes fewer than this truncates at publish and says so.

max items 500

drxSkustring

Your own design SKU. Omitted = minted from the workspace's configured SKU format. A workspace that prefixes SKUs with the member who built the listing has no member to read here, so an API-created listing takes the title-derived prefix instead; send this field to control the value yourself.

max length 191

Explicit variants. Omitted = expanded from the template’s variation axes and pricing grid.

variablesobject

Values for {placeholders} in the template title/description.

highlightsstring[]

TikTok only: this listing’s OWN Product highlights, one entry per bullet. Omitted or empty = the listing publishes its template’s (inheritedHighlights), and a list equal to the template’s is stored as none so the listing keeps following it. Entries are trimmed and blank ones dropped; more than 5 entries, or more than 1,500 characters (Unicode code points) across them, is refused with validation_failed. The workspace’s active text-replacement rules apply, as they do to the description.

Responses

201ProductResponse
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/products' \
  -H "Authorization: Bearer $DOCTORX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "string",
  "templateId": "string",
  "channel": "tiktok",
  "price": 0
}'

Every variant, SKU, price, stock, image, per-listing attribute override, the inherited template attributes, the fixed images the template adds to the gallery, the live category id, and per-shop sync + marketplace review state.

Parameters

NameInTypeDescription
idrequired
pathstring

Responses

200ProductResponse
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/products/string' \
  -H "Authorization: Bearer $DOCTORX_API_KEY"
PATCH/products/{id}

A changed title is propagated to the design’s siblings on other channels, clamped to each channel’s limit at a word boundary. attributes: [] clears per-listing overrides and returns to inheriting the template. A product merged into another listing (mergedIntoId set) refuses price and compareAtPrice, and a changed templateId or drxSku, with 409 product_merged: its design is sold on that listing, whose orders for it are fulfilled from this product’s variants. Its content and cost stay editable.

Parameters

NameInTypeDescription
idrequired
pathstring

Request body

titlestring

min length 1 · max length 500

pricenumber

min 0

compareAtPricenumber | null
costnumber

Production cost for this listing, USD: written on the product and on EVERY variant, and on the variants of its cross-listed siblings. To change one variant, use PATCH /products/{id}/variants.

min 0

descriptionstring
categorystring
tagsstring[]
highlightsstring[]

TikTok only: replaces this listing’s own Product highlights, one entry per bullet; [] clears them and the listing returns to its template’s. Entries are trimmed and blank ones dropped; more than 5 entries, or more than 1,500 characters (Unicode code points) across them, is refused with validation_failed. Reaches TikTok on the listing’s next publish or update.

imagesstring (uri)[]

Replaces the listing’s own gallery; a template’s fixedImages are published after it and are not part of this list. Bounded exactly as the dashboard write path is - the same 500-image ceiling and the same 2000-character limit per URL - so a listing a partner can build is a listing the dashboard can build.

max items 500

videoUrlstring (uri) | null
statusstring

DoctorX-side listing lifecycle state.

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

templateIdstring

Re-link to a different template: its category, and the variant matrix rebuilt from its axes. A surviving variant keeps its SKU and stock, except on a product imported by the crawler, where a variant still holding what was copied from the source shop takes the template’s SKU and stock. A variant takes the new template’s cost unless a cost was set by hand: one still equal to what the previous template stated follows the new one. To give one listing a category without this, use PUT /products/{id}/channel-setup.

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

drxSkustring

max length 191

Per-listing overrides. [] clears them and returns to inheriting the template.

Responses

200ProductResponse
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 PATCH 'https://api.doctorx.vn/api/public/v1/products/string' \
  -H "Authorization: Bearer $DOCTORX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

Every per-channel sibling of this design. A design never cross-listed returns just itself with groupId: null.

Parameters

NameInTypeDescription
idrequired
pathstring

Responses

200ProductGroupResponse
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/products/string/group' \
  -H "Authorization: Bearer $DOCTORX_API_KEY"
GET/products/{id}/metrics

Etsy: the listing's views, favorites, sales and conversion rate per day, for each shop of the product the key may see, from DoctorX's own daily copy (kept 400 days; the marketplace connection itself keeps only the last 8). Days are the connection's calendar days, oldest first per shop. The newest days are still filling: a day's views can read 0 until the connection reports them during the following day, and the day is corrected then. Amazon listings are not measured, so an Amazon product answers an empty list, never zeros, and so does a product with no listing yet. The lifetime totals are shopSyncs[].metrics on the product.

Parameters

NameInTypeDescription
idrequired
pathstring
shopId
querystring

Only this shop's listing of the product. Default: every shop the key may see.

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

from
querystring

First day, inclusive (YYYY-MM-DD). Default: 29 days before to.

pattern ^\d{4}-\d{2}-\d{2}$

to
querystring

Last day, inclusive (YYYY-MM-DD). Default: today (UTC).

pattern ^\d{4}-\d{2}-\d{2}$

Responses

200ProductMetricsListResponse
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/products/string/metrics' \
  -H "Authorization: Bearer $DOCTORX_API_KEY"
GET/products/{id}/cross-list-readiness

Pre-validate before publishing. A channel is ineligible when the design’s template does not target it, since the marketplace category can only come from a template.

Parameters

NameInTypeDescription
idrequired
pathstring

Responses

200CrossListReadinessResponse
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/products/string/cross-list-readiness' \
  -H "Authorization: Bearer $DOCTORX_API_KEY"

Only variants belonging to this product are applied. The product-level price/cost snapshot is recomputed from the cheapest enabled variant afterwards. On a product merged into another listing (mergedIntoId set) only cost is accepted, and anything else is refused with 409 product_merged: set its price, list price, stock and image on the listing it was merged into.

Parameters

NameInTypeDescription
idrequired
pathstring

Request body

min items 1 · max items 5000

Responses

200ProductResponse
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 PATCH 'https://api.doctorx.vn/api/public/v1/products/string/variants' \
  -H "Authorization: Bearer $DOCTORX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "variants": [
    {
      "id": "string",
      "price": 0,
      "listPrice": 0,
      "cost": 0,
      "stock": 0,
      "imageUrl": "https://example.com",
      "weight": {
        "value": 0,
        "unit": "kg"
      }
    }
  ]
}'

Use this, NOT PATCH /products/{id} with a templateId, to set the category of a listing that has none - in particular anything imported by a crawl. The PATCH route rebinds a REUSABLE template, which clears an imported description and rebuilds the variant matrix from the template’s axes; on an imported listing both are silent data loss, and the variant SKUs are also the join key for cost history. This route writes the category binding and nothing else. It is REFUSED with 400 when the listing already uses a SHARED template, because the category would then come from that template and changing it would re-categorise every other listing using it; unlink the template first, or change it on the template knowingly. A product merged into another listing (mergedIntoId set) is refused with 409 product_merged: it is never published on its own.

Parameters

NameInTypeDescription
idrequired
pathstring

Request body

categoryIdstringrequired

The live channel LEAF category id. REQUIRED, and deliberately not name-with-a-fallback: DoctorX refuses to turn a category NAME into an id for TikTok, Etsy and Amazon, so a request carrying only a name would store a setup that still cannot publish. Get it from GET /templates/categories.

min length 1 · max length 64

categoryNamestringrequired

Display name for the chosen category. Stored, never published.

min length 1 · max length 300

categoryPathstring[]

Ancestor-first display path from the category picker.

max items 12

categoryVersionstring

TikTok taxonomy version. Derived from the shop's region when omitted.

One of: "v1", "v2"

Every field optional, and an omitted value means "use the default" (0.5 kg, 10x10x10 cm) rather than zero.

warehouseIdstring

TikTok warehouse id from GET /authorize/shops/{id}/warehouses. Omitted lets the channel resolve the shop's default, so this is a preference and never a requirement.

max length 64

THREE STATES AND null IS ONE OF THEM: omitted leaves whatever the listing holds, null turns a made-to-order listing back into a regular one, an object sets the window. The RANGES depend on the shop region and are checked server-side, which names the valid range when it refuses.

Responses

200ProductResponse
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 PUT 'https://api.doctorx.vn/api/public/v1/products/string/channel-setup' \
  -H "Authorization: Bearer $DOCTORX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "categoryId": "string",
  "categoryName": "string"
}'

The package a publish sends is decided per part: what you set here, else the template package, else the weight the DrX CrawlBot read off the source page (weight only), else the default (0.5 and 10 x 10 x 10). null clears a part, an omitted part is left as it is. The cross-listed copies of the same design on other channels take the same package. A product merged into another listing (mergedIntoId set) is refused with 409 product_merged: it ships under that listing package. A variant weight of its own is set with PATCH /products/{id}/variants.

Parameters

NameInTypeDescription
idrequired
pathstring

Request body

The listing package weight, used over the template package. null clears it (the template package, else the weight the CrawlBot read, else 0.5). Omitted leaves it as it is.

The box, all three sides, used over the template box. null clears it (the template box, else 10 x 10 x 10). Omitted leaves it as it is.

Responses

200ProductResponse
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 PUT 'https://api.doctorx.vn/api/public/v1/products/string/package' \
  -H "Authorization: Bearer $DOCTORX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
POST/products/delete

LOCAL ONLY: any live listing keeps running on its channel. End the listing first with /products/{id}/end-listing if you want it off sale, otherwise you orphan a listing DoctorX can no longer manage. A product combined into another listing (mergedIntoId set) is kept while that listing exists and is not counted in deleted; deleting that listing gives it back as an ordinary product.

Request body

idsstring[]required

Product ids to delete locally. The marketplace listing is NOT ended.

min items 1 · max items 500

Responses

200DeleteResultResponse
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/products/delete' \
  -H "Authorization: Bearer $DOCTORX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "ids": [
    "string"
  ]
}'

Targets must be on the same channel as the product; use cross-list for other marketplaces. The publish is QUEUED and this call returns as soon as it is accepted, so succeeded and failed are 0 and scheduled is true: read the outcome from the product’s shopSyncs, or subscribe to product.published / product.publish_failed. scheduleAt and delaySeconds choose WHEN it runs rather than whether it is queued. On a TikTok shop at its listing limit a publish may take a little longer to start. A product mirroring an existing marketplace listing is refused, and so is a product combined into another listing (mergedIntoId set, failures[].code publish_blocked): publish that listing instead. A product made from a pulled TikTok listing is refused on the one shop that still holds that listing (blocked, failures[].code publish_blocked) and published on every other.

Parameters

NameInTypeDescription
idrequired
pathstring

Request body

shopIdsstring[]required

Target shops. Each must be on the same channel as the product.

min items 1 · max items 100

saveModestring

AS_DRAFT saves a marketplace draft under relaxed validation instead of going live.

One of: "LISTING", "AS_DRAFT"

default "LISTING"

scheduleAtstring (date-time) | string (date)

Publish at this instant instead of now. Enqueued asynchronously.

delaySecondsinteger

Stagger between listings so a batch does not hit the channel at once.

min 0 · max 86400

Responses

200PublishResultResponse
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/products/string/publish' \
  -H "Authorization: Bearer $DOCTORX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "shopIds": [
    "string"
  ]
}'
POST/products/{id}/cross-list

Routes each target shop to this design’s per-channel sibling, creating it on demand from the template. At most one sibling exists per channel, so concurrent calls cannot create duplicate listings. A listing that combines several designs (mergeAxis set) stays on its own marketplace, and a product combined into another listing (mergedIntoId set) is not published at all: both are reported with publish_blocked. So is a product made from a pulled TikTok listing, on the one shop that still holds that listing.

Parameters

NameInTypeDescription
idrequired
pathstring

Request body

shopIdsstring[]required

Target shops, which MAY span several marketplaces. The per-channel sibling is created on demand.

min items 1 · max items 100

saveModestring

One of: "LISTING", "AS_DRAFT"

default "LISTING"

scheduleAtstring (date-time) | string (date)

ISO-8601 instant in UTC (e.g. 2026-07-28T19:16:01.294Z). A bare calendar day (2026-07-28) is also accepted: as a lower bound it means the start of that day, as an upper bound the end of it, so both bounds are inclusive.

delaySecondsinteger

min 0 · max 86400

Responses

200PublishResultResponse
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/products/string/cross-list' \
  -H "Authorization: Bearer $DOCTORX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "shopIds": [
    "string"
  ]
}'
POST/products/{id}/end-listing

Takes the listing off sale WITHOUT deleting the local product. Amazon cannot do this through DoctorX: check capabilities.endListing on GET /channels first.

Parameters

NameInTypeDescription
idrequired
pathstring

Responses

200EndListingResponse
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/products/string/end-listing' \
  -H "Authorization: Bearer $DOCTORX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
POST/products/bulk/add-images

Appends to each gallery rather than replacing it. The per-channel image cap is applied to the RESULTING total, so a product already near its limit is reported in message instead of being silently truncated. Every id is validated against your tenant and your key binding BEFORE anything is written: a bulk write that quietly does less than it was asked is worse than one that refuses.

Request body

productIdsstring[]required

Products to append to. Every id must belong to your tenant.

min items 1 · max items 500

imagesstring (uri)[]required

Image URLs to APPEND to each gallery. The per-channel cap is enforced on the RESULTING total, not on this list, so a product already near its limit is reported in message rather than silently truncated.

min items 1 · max items 40

Responses

200BulkResultResponse
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/products/bulk/add-images' \
  -H "Authorization: Bearer $DOCTORX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "productIds": [
    "string"
  ],
  "images": [
    "https://example.com"
  ]
}'
POST/products/bulk/change-template

Rebinds the category, policies and variation axes each product inherits. The template must TARGET each product’s channel, or that product is refused rather than bound to a template that would publish garbage. Variant SKUs are realigned exactly as a dashboard rebind realigns them, so a rebind cannot rename the SKU a live listing is keyed on - with one exception: on a product imported by the crawler, a variant still holding the SKU and stock copied from the source shop takes the SKU and stock the template gives that combination, and keeps only its photo. Its SKU still stays where a new one would replace a live listing rather than edit it (eBay, Etsy and Amazon while the listing is live). So is a listing that combines several designs (mergeAxis set: a rebind would rebuild its variants and drop the designs), and a product merged into another listing (mergedIntoId set: that listing fulfils its design from this product’s variants).

Request body

productIdsstring[]required

min items 1 · max items 500

templateIdstringrequired

Template to re-link to. It must target each product’s channel, or that product is refused rather than bound to a template that would publish garbage.

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

200BulkResultResponse
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/products/bulk/change-template' \
  -H "Authorization: Bearer $DOCTORX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "productIds": [
    "string"
  ],
  "templateId": "string"
}'

The workspace SKU format is FORWARD-ONLY: changing it applies to new listings and rewrites nothing that exists. This is the only bulk rewrite. THE UNIT OF WORK IS THE CROSS-LISTING GROUP, not the row - one design shares its drxSku with its per-channel siblings, so naming any member re-mints the whole group. A drxSku already on the current format is KEPT and only the variant SKUs that are not built on it change; a listing imported by the crawler has the variant SKUs copied from the source shop re-minted too. A TikTok variant SKU longer than 50 characters (TikTok's documented seller_sku limit, which the UK market enforces) is shortened to fit when the product is bound for the UK - its template targets the UK, or it has a shopSyncs entry on a UK shop - the whole product to one width with the drxSku kept at its start; a product bound only for US shops keeps its SKUs. It is LOCAL: a re-minted SKU does not reach the marketplace until the listing is published again, and on eBay the seller SKU IS the inventory item, so a re-publish under a new SKU creates a second inventory item rather than renaming the first. Three things are REFUSED and each refusal is named in refusedReasons: a design whose SKU the SELLER typed (that identifier is theirs; only the TikTok variant SKUs over 50 characters of a product bound for the UK are shortened, and the typed drxSku stays), a PULLED listing (it mirrors the shop's own listing and its SKUs are the channel's), and a product merged into another listing (mergedIntoId set: its own listing's orders join on its SKUs, and the merged listing fulfils its design from its variants).

Request body

idsstring[]required

Product ids. THE UNIT OF WORK IS THE CROSS-LISTING GROUP, NOT THE ROW: one design shares its drxSku with its per-channel siblings, so naming any member re-mints the whole group whether or not you listed the others. Minting per row would hand two siblings different values and split a group nothing would re-join.

min items 1 · max items 200

Responses

200RegenerateSkusResultResponse
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/products/bulk/regenerate-skus' \
  -H "Authorization: Bearer $DOCTORX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "ids": [
    "string"
  ]
}'
POST/products/import-csv

The TTS bulk-listing format. Rows group into products by handle (falling back to title), so one file carries a full variant matrix with one row per variant. Capped at 5,000 rows. Rejected rows are reported individually in errors and never abort the rest of the file.

Request body

contentstringrequired

The CSV itself, as text. Rows are grouped into products by handle (falling back to title), so one file can carry a full variant matrix with one row per variant. Capped at 5,000 rows, applied DURING the scan rather than after, so an oversized upload is never fully materialised first.

min length 1 · max length 20000000

fileNamestring

Recorded on the import for traceability.

max length 255 · default "import.csv"

Responses

200ImportCsvResultResponse
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/products/import-csv' \
  -H "Authorization: Bearer $DOCTORX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "content": "string"
}'
POST/products/resync/{shopId}

Starts re-publishing the shop’s synced listings to that shop in the background and answers at once: queued counts the listings it will send, and each product’s shopSyncs[] carries its own result as the re-push reaches it. While another bulk action on your products is running, the call is refused with publish_blocked; try again when it has finished. PULLED mirrors are left out, because re-publishing one would overwrite a listing DoctorX did not create. Needs products:publish, not products:write, because it pushes to a live marketplace.

Parameters

NameInTypeDescription
shopIdrequired
pathstring

Responses

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