Versión de API

V2 · nuevas integraciones V1 · integraciones existentes

Productos

Contrato aprobado · en validación

La referencia detallada de campos se muestra en inglés. Los identificadores y valores de API no cambian.

Create a product, parent, variant or component product.

Permisos necesarios

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

Parámetros

`Idempotency-Key` header · Obligatorio	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 · Obligatorio

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.

Solicitud

`type` string · Obligatorio	["single","parent","variant","bundle","assembly","virtual"]
`sku` string · Opcional
`name` string · Obligatorio
`status` string · Opcional	["active","inactive"]
`description` string · Opcional
`barcode` string · Opcional
`upc` string · Opcional
`ean` string · Opcional
`gtin` string · Opcional
`brand` string · Opcional
`manufacturer` string · Opcional
`currency` string · Opcional
`salePrice` string · Opcional	Non-negative decimal monetary amount as a string; never IEEE floating point.
`trackInventory` boolean · Opcional
`parentId` string · Opcional	Stable Shipbuy resource identifier serialized as a string. Treat as opaque; never confuse with a carrier identifier or display number.
`variantOptions` array · Opcional
`variantSelection` object · Opcional	Selected axis/value pairs. Axis names and values must belong to the parent options; the normalized combination is unique within the parent.
`components` array · Opcional
`shippingDefaults` object · Opcional	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 · Opcional
`metadata` object · Opcional	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
}

Respuesta

`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.

Descargar contrato 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.

Permisos necesarios

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

Parámetros

`cursor` query · Opcional	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 · Opcional	integer
`updatedAfter` query · Opcional	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 · Opcional	string
`parentId` query · Opcional	string
`type` query · Opcional	string
`status` query · Opcional	string
`query` query · Opcional	string

Respuesta

`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.

Descargar contrato V2 (JSON)

Retrieve a product with options and components.

Permisos necesarios

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

Parámetros

`productId` path · Obligatorio	string

Respuesta

`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.

Descargar contrato V2 (JSON)

Edit or inactivate a product.

Permisos necesarios

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

Parámetros

`productId` path · Obligatorio	string
`Idempotency-Key` header · Obligatorio	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 · Obligatorio	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.

Solicitud

`sku` string · Opcional
`name` string · Opcional
`status` string · Opcional	["active","inactive"]
`description` string · Opcional
`barcode` string · Opcional
`upc` string · Opcional
`ean` string · Opcional
`gtin` string · Opcional
`brand` string · Opcional
`manufacturer` string · Opcional
`currency` string · Opcional
`salePrice` string · Opcional	Non-negative decimal monetary amount as a string; never IEEE floating point.
`trackInventory` boolean · Opcional
`parentId` string · Opcional	Stable Shipbuy resource identifier serialized as a string. Treat as opaque; never confuse with a carrier identifier or display number.
`variantOptions` array · Opcional
`variantSelection` object · Opcional	Selected axis/value pairs. Axis names and values must belong to the parent options; the normalized combination is unique within the parent.
`components` array · Opcional
`shippingDefaults` object · Opcional	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 · Opcional
`metadata` object · Opcional	Client-owned string metadata only. No secrets or card data. Not used for authorization or business rules.

{
  "status": "inactive"
}

Respuesta

`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.

Descargar contrato 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.

Permisos necesarios

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

Parámetros

productId

path · Obligatorio

string

Idempotency-Key

header · Obligatorio

Solicitud

`reason` string · Obligatorio

{
  "reason": "Product discontinued"
}

Respuesta

`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.

Descargar contrato V2 (JSON)

Productos

Create a product, parent, variant or component product

Permisos necesarios

Parámetros

Solicitud

Respuesta

List the unified product catalog

Permisos necesarios

Parámetros

Respuesta

Retrieve a product with options and components

Permisos necesarios

Parámetros

Respuesta

Edit or inactivate a product

Permisos necesarios

Parámetros

Solicitud

Respuesta

Inactivate a product without deleting its history

Permisos necesarios

Parámetros

Solicitud

Respuesta

En esta página

Productos

POST/v2/productsCreate a product, parent, variant or component productNo disponible

Create a product, parent, variant or component product

Permisos necesarios

Parámetros

Solicitud

Respuesta

GET/v2/productsList the unified product catalogNo disponible

List the unified product catalog

Permisos necesarios

Parámetros

Respuesta

GET/v2/products/{productId}Retrieve a product with options and componentsNo disponible

Retrieve a product with options and components

Permisos necesarios

Parámetros

Respuesta

PATCH/v2/products/{productId}Edit or inactivate a productNo disponible

Edit or inactivate a product

Permisos necesarios

Parámetros

Solicitud

Respuesta

POST/v2/products/{productId}/archiveInactivate a product without deleting its historyNo disponible

Inactivate a product without deleting its history

Permisos necesarios

Parámetros

Solicitud

Respuesta