Products
Products, variants, per-shop listings and publishing.
/productsCursor-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
| 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" |
status | query | string | DoctorX-side listing lifecycle state. One of: "draft", "ready", "live", "error", "archived" |
source | query | string | How the listing entered DoctorX. One of: "template", "pod", "pulled", "csv", "crawlbot" |
templateId | 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}$ |
shopId | query | string | 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 | query | string | Narrow the shopId match to a specific push state, e.g. One of: "pending", "syncing", "synced", "failed" |
drxSku | query | string | Exact match on the seller design SKU. |
search | query | string | 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 ( |
updatedSince | query | string (date-time) | string (date) | Only products updated at or after this instant. Pair it with |
sortBy | query | string | Sort key. STATED rather than inferred from One of: "createdAt", "updatedAt" default "createdAt" |
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/products' \
-H "Authorization: Bearer $DOCTORX_API_KEY"/productsThe 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
titlestringrequiredmin length 1 · max length 500
templateIdstringrequiredTemplate 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}$
channelstringrequiredMarketplace channel.
One of: "tiktok", "ebay", "etsy", "amazon"
pricenumberrequiredmin 0
descriptionstringdefault ""
costnumberProduction 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
drxSkustringYour 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.
variablesobjectValues 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
| 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/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
}'/products/{id}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
| 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/products/string' \
-H "Authorization: Bearer $DOCTORX_API_KEY"/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
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Request body
titlestringmin length 1 · max length 500
pricenumbermin 0
compareAtPricenumber | nullcostnumberProduction 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
descriptionstringcategorystringtagsstring[]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) | nullstatusstringDoctorX-side listing lifecycle state.
One of: "draft", "ready", "live", "error", "archived"
templateIdstringRe-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}$
drxSkustringmax length 191
Per-listing overrides. [] clears them and returns to inheriting the template.
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 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 '{}'/products/{id}/groupEvery per-channel sibling of this design. A design never cross-listed returns just itself with groupId: null.
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/products/string/group' \
-H "Authorization: Bearer $DOCTORX_API_KEY"/products/{id}/metricsEtsy: 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
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string | |
shopId | query | string | 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 | query | string | First day, inclusive (YYYY-MM-DD). Default: 29 days before pattern ^\d{4}-\d{2}-\d{2}$ |
to | query | string | Last day, inclusive (YYYY-MM-DD). Default: today (UTC). pattern ^\d{4}-\d{2}-\d{2}$ |
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/products/string/metrics' \
-H "Authorization: Bearer $DOCTORX_API_KEY"/products/{id}/cross-list-readinessPre-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
| 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/products/string/cross-list-readiness' \
-H "Authorization: Bearer $DOCTORX_API_KEY"/products/{id}/variantsOnly 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
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Request body
min items 1 · max items 5000
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 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"
}
}
]
}'/products/{id}/channel-setupUse 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
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Request body
categoryIdstringrequiredThe 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
categoryNamestringrequiredDisplay 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
categoryVersionstringTikTok 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.
warehouseIdstringTikTok 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
| 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 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"
}'/products/{id}/packageThe 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
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
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
| 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 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 '{}'/products/deleteLOCAL 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[]requiredProduct ids to delete locally. The marketplace listing is NOT ended.
min items 1 · max items 500
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/products/delete' \
-H "Authorization: Bearer $DOCTORX_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"ids": [
"string"
]
}'/products/{id}/publishTargets 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
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Request body
shopIdsstring[]requiredTarget shops. Each must be on the same channel as the product.
min items 1 · max items 100
saveModestringAS_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.
delaySecondsintegerStagger between listings so a batch does not hit the channel at once.
min 0 · max 86400
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/products/string/publish' \
-H "Authorization: Bearer $DOCTORX_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"shopIds": [
"string"
]
}'/products/{id}/cross-listRoutes 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
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Request body
shopIdsstring[]requiredTarget shops, which MAY span several marketplaces. The per-channel sibling is created on demand.
min items 1 · max items 100
saveModestringOne 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.
delaySecondsintegermin 0 · max 86400
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/products/string/cross-list' \
-H "Authorization: Bearer $DOCTORX_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"shopIds": [
"string"
]
}'/products/{id}/end-listingTakes the listing off sale WITHOUT deleting the local product. Amazon cannot do this through DoctorX: check capabilities.endListing on GET /channels first.
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/products/string/end-listing' \
-H "Authorization: Bearer $DOCTORX_API_KEY" \
-H "Idempotency-Key: $(uuidgen)"/products/bulk/add-imagesAppends 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[]requiredProducts to append to. Every id must belong to your tenant.
min items 1 · max items 500
imagesstring (uri)[]requiredImage 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
| 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/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"
]
}'/products/bulk/change-templateRebinds 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[]requiredmin items 1 · max items 500
templateIdstringrequiredTemplate 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
| 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/products/bulk/change-template' \
-H "Authorization: Bearer $DOCTORX_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"productIds": [
"string"
],
"templateId": "string"
}'/products/bulk/regenerate-skusThe 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[]requiredProduct 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
| 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/products/bulk/regenerate-skus' \
-H "Authorization: Bearer $DOCTORX_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"ids": [
"string"
]
}'/products/import-csvThe 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
contentstringrequiredThe 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
fileNamestringRecorded on the import for traceability.
max length 255 · default "import.csv"
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/products/import-csv' \
-H "Authorization: Bearer $DOCTORX_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"content": "string"
}'/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
| Name | In | Type | Description |
|---|---|---|---|
shopIdrequired | 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/products/resync/string' \
-H "Authorization: Bearer $DOCTORX_API_KEY" \
-H "Idempotency-Key: $(uuidgen)"