API 版本

产品

契约已确认 · 验证中

详细字段参考以英文显示；字段名和 API 值保持不变。

Create a product, parent, variant or component product.

所需权限

{
  "anyOf": [
    {
      "allOf": [
        "products.write"
      ]
    }
  ]
}

参数

`Idempotency-Key` header · 必填	Required on every business write, including quotes, verification and DELETE. New logical action=new key; retry=same key and canonical payload. Namespace account+environment+stable integrationId+HTTP method+canonical path; credential rotation within one integration preserves integrationId. Same key/different payload=409. Lookup follows authentication/resource authorization and precedes If-Match/freshness checks so a completed retry returns its first result. General receipts retained >=7 days; financial/inventory side effects retain durable business association or tombstone beyond receipt expiry to prevent re-execution. In-flight/unknown result returns its operation, never a blind repurchase. Secret-creation responses are the deliberate exception to identical replay: the resource is replayed, but its one-time secret is null with secretUnavailable=true; use management rotation to recover.

Idempotency-Key

header · 必填

Required on every business write, including quotes, verification and DELETE. New logical action=new key; retry=same key and canonical payload. Namespace account+environment+stable integrationId+HTTP method+canonical path; credential rotation within one integration preserves integrationId. Same key/different payload=409. Lookup follows authentication/resource authorization and precedes If-Match/freshness checks so a completed retry returns its first result. General receipts retained >=7 days; financial/inventory side effects retain durable business association or tombstone beyond receipt expiry to prevent re-execution. In-flight/unknown result returns its operation, never a blind repurchase. Secret-creation responses are the deliberate exception to identical replay: the resource is replayed, but its one-time secret is null with secretUnavailable=true; use management rotation to recover.

请求

`type` string · 必填	["single","parent","variant","bundle","assembly","virtual"]
`sku` string · 可选
`name` string · 必填
`status` string · 可选	["active","inactive"]
`description` string · 可选
`barcode` string · 可选
`upc` string · 可选
`ean` string · 可选
`gtin` string · 可选
`brand` string · 可选
`manufacturer` string · 可选
`currency` string · 可选
`salePrice` string · 可选	Non-negative decimal monetary amount as a string; never IEEE floating point.
`trackInventory` boolean · 可选
`parentId` string · 可选	Stable Shipbuy resource identifier serialized as a string. Treat as opaque; never confuse with a carrier identifier or display number.
`variantOptions` array · 可选
`variantSelection` object · 可选	Selected axis/value pairs. Axis names and values must belong to the parent options; the normalized combination is unique within the parent.
`components` array · 可选
`shippingDefaults` object · 可选	Optional product shipping defaults, not an actual package or inventory quantity. Partial defaults can be stored; incomplete dimensions/weight do not create a valid shipping plan automatically.
`customs` object · 可选
`metadata` object · 可选	Client-owned string metadata only. No secrets or card data. Not used for authorization or business rules.

{
  "type": "single",
  "sku": "TEE-BLK-M",
  "name": "Black cotton T-shirt M",
  "currency": "USD",
  "salePrice": "19.95",
  "trackInventory": true
}

返回结果

`201`	Success.
`400`	Malformed JSON, unsupported query or invalid request syntax.
`401`	Missing, invalid, expired or revoked API key credential.
`403`	Scope, tenant/environment/warehouse/carrier-account constraint or plan entitlement denied. New live external-tracker registration and standalone address verification also return service_not_enabled until price and quota policies are confirmed; no upstream call or new fee/accrual is permitted.
`404`	Resource absent or not visible in the authorized tenant/environment.
`409`	Business conflict, changed idempotency payload, stale quote, pending side effect or insufficient stock/funds.
`422`	Field/business validation failed; details identify invalid fields.
`429`	Rate or paid-service limit exceeded. Respect Retry-After.
`500`	Unexpected server error; use requestId and query operation before retrying a side effect.
`503`	Service temporarily unavailable; upstream outcome may be unknown, query/replay the operation.

下载 V2 契约（JSON）

All six types are first-class products. parentId selects variants; component definitions are on bundle/assembly products. No separate variants or SKU inventory master is introduced.

所需权限

{
  "anyOf": [
    {
      "allOf": [
        "products.read"
      ]
    }
  ]
}

参数

`cursor` query · 可选	Opaque continuation bound to tenant/environment/integration scope, filters, snapshot high-watermark and stable sort (updatedAt,id or documented resource-specific sort). Do not alter filters between pages. Incremental synchronization must include archive/deletion tombstones within the published retention window; snapshot expiry fails explicitly and requires a new scan.
`limit` query · 可选	integer
`updatedAfter` query · 可选	Exclusive UTC updated-time lower bound. For incremental sync keep a small overlap and deduplicate by id/version; cursor is authoritative within a scan.
`sku` query · 可选	string
`parentId` query · 可选	string
`type` query · 可选	string
`status` query · 可选	string
`query` query · 可选	string

返回结果

`200`	Success.
`400`	Malformed JSON, unsupported query or invalid request syntax.
`401`	Missing, invalid, expired or revoked API key credential.
`403`	Scope, tenant/environment/warehouse/carrier-account constraint or plan entitlement denied. New live external-tracker registration and standalone address verification also return service_not_enabled until price and quota policies are confirmed; no upstream call or new fee/accrual is permitted.
`404`	Resource absent or not visible in the authorized tenant/environment.
`409`	Business conflict, changed idempotency payload, stale quote, pending side effect or insufficient stock/funds.
`422`	Field/business validation failed; details identify invalid fields.
`429`	Rate or paid-service limit exceeded. Respect Retry-After.
`500`	Unexpected server error; use requestId and query operation before retrying a side effect.
`503`	Service temporarily unavailable; upstream outcome may be unknown, query/replay the operation.

下载 V2 契约（JSON）

Retrieve a product with options and components.

所需权限

{
  "anyOf": [
    {
      "allOf": [
        "products.read"
      ]
    }
  ]
}

参数

`productId` path · 必填	string

返回结果

`200`	Success.
`400`	Malformed JSON, unsupported query or invalid request syntax.
`401`	Missing, invalid, expired or revoked API key credential.
`403`	Scope, tenant/environment/warehouse/carrier-account constraint or plan entitlement denied. New live external-tracker registration and standalone address verification also return service_not_enabled until price and quota policies are confirmed; no upstream call or new fee/accrual is permitted.
`404`	Resource absent or not visible in the authorized tenant/environment.
`409`	Business conflict, changed idempotency payload, stale quote, pending side effect or insufficient stock/funds.
`422`	Field/business validation failed; details identify invalid fields.
`429`	Rate or paid-service limit exceeded. Respect Retry-After.
`500`	Unexpected server error; use requestId and query operation before retrying a side effect.
`503`	Service temporarily unavailable; upstream outcome may be unknown, query/replay the operation.

下载 V2 契约（JSON）

Edit or inactivate a product.

所需权限

{
  "anyOf": [
    {
      "allOf": [
        "products.write"
      ]
    }
  ]
}

参数

`productId` path · 必填	string
`Idempotency-Key` header · 必填	Required on every business write, including quotes, verification and DELETE. New logical action=new key; retry=same key and canonical payload. Namespace account+environment+stable integrationId+HTTP method+canonical path; credential rotation within one integration preserves integrationId. Same key/different payload=409. Lookup follows authentication/resource authorization and precedes If-Match/freshness checks so a completed retry returns its first result. General receipts retained >=7 days; financial/inventory side effects retain durable business association or tombstone beyond receipt expiry to prevent re-execution. In-flight/unknown result returns its operation, never a blind repurchase. Secret-creation responses are the deliberate exception to identical replay: the resource is replayed, but its one-time secret is null with secretUnavailable=true; use management rotation to recover.
`If-Match` header · 必填	Exact strong ETag from the latest resource read. Required for PATCH; absent=428, stale=412. Quote/ship/split actions use explicit expectedVersion. An authorized idempotent replay returns its original committed result even if the resource is now newer.

请求

`sku` string · 可选
`name` string · 可选
`status` string · 可选	["active","inactive"]
`description` string · 可选
`barcode` string · 可选
`upc` string · 可选
`ean` string · 可选
`gtin` string · 可选
`brand` string · 可选
`manufacturer` string · 可选
`currency` string · 可选
`salePrice` string · 可选	Non-negative decimal monetary amount as a string; never IEEE floating point.
`trackInventory` boolean · 可选
`parentId` string · 可选	Stable Shipbuy resource identifier serialized as a string. Treat as opaque; never confuse with a carrier identifier or display number.
`variantOptions` array · 可选
`variantSelection` object · 可选	Selected axis/value pairs. Axis names and values must belong to the parent options; the normalized combination is unique within the parent.
`components` array · 可选
`shippingDefaults` object · 可选	Optional product shipping defaults, not an actual package or inventory quantity. Partial defaults can be stored; incomplete dimensions/weight do not create a valid shipping plan automatically.
`customs` object · 可选
`metadata` object · 可选	Client-owned string metadata only. No secrets or card data. Not used for authorization or business rules.

{
  "status": "inactive"
}

返回结果

`200`	Success.
`400`	Malformed JSON, unsupported query or invalid request syntax.
`401`	Missing, invalid, expired or revoked API key credential.
`403`	Scope, tenant/environment/warehouse/carrier-account constraint or plan entitlement denied. New live external-tracker registration and standalone address verification also return service_not_enabled until price and quota policies are confirmed; no upstream call or new fee/accrual is permitted.
`404`	Resource absent or not visible in the authorized tenant/environment.
`409`	Business conflict, changed idempotency payload, stale quote, pending side effect or insufficient stock/funds.
`412`	If-Match does not match the current resource revision.
`422`	Field/business validation failed; details identify invalid fields.
`428`	Required concurrency precondition missing.
`429`	Rate or paid-service limit exceeded. Respect Retry-After.
`500`	Unexpected server error; use requestId and query operation before retrying a side effect.
`503`	Service temporarily unavailable; upstream outcome may be unknown, query/replay the operation.

下载 V2 契约（JSON）

Sets status=inactive through the normal product service. Does not hard-delete, remove BOM links, cancel orders or mutate stock. Existing reference/type business guards still apply; replay returns the original result.

所需权限

{
  "anyOf": [
    {
      "allOf": [
        "products.write"
      ]
    }
  ]
}

参数

productId

path · 必填

string

Idempotency-Key

header · 必填

请求

`reason` string · 必填

{
  "reason": "Product discontinued"
}

返回结果

`200`	Success.
`400`	Malformed JSON, unsupported query or invalid request syntax.
`401`	Missing, invalid, expired or revoked API key credential.
`403`	Scope, tenant/environment/warehouse/carrier-account constraint or plan entitlement denied. New live external-tracker registration and standalone address verification also return service_not_enabled until price and quota policies are confirmed; no upstream call or new fee/accrual is permitted.
`404`	Resource absent or not visible in the authorized tenant/environment.
`409`	Business conflict, changed idempotency payload, stale quote, pending side effect or insufficient stock/funds.
`422`	Field/business validation failed; details identify invalid fields.
`429`	Rate or paid-service limit exceeded. Respect Retry-After.
`500`	Unexpected server error; use requestId and query operation before retrying a side effect.
`503`	Service temporarily unavailable; upstream outcome may be unknown, query/replay the operation.

下载 V2 契约（JSON）

产品

Create a product, parent, variant or component product

所需权限

参数

请求

返回结果

List the unified product catalog

所需权限

参数

返回结果

Retrieve a product with options and components

所需权限

参数

返回结果

Edit or inactivate a product

所需权限

参数

请求

返回结果

Inactivate a product without deleting its history

所需权限

参数

请求

返回结果

本篇目录

产品

POST/v2/productsCreate a product, parent, variant or component product尚未开放

Create a product, parent, variant or component product

所需权限

参数

请求

返回结果

GET/v2/productsList the unified product catalog尚未开放

List the unified product catalog

所需权限

参数

返回结果

GET/v2/products/{productId}Retrieve a product with options and components尚未开放

Retrieve a product with options and components

所需权限

参数

返回结果

PATCH/v2/products/{productId}Edit or inactivate a product尚未开放

Edit or inactivate a product

所需权限

参数

请求

返回结果

POST/v2/products/{productId}/archiveInactivate a product without deleting its history尚未开放

Inactivate a product without deleting its history

所需权限

参数

请求

返回结果