ShipBuy

API version
V2 · new integrationsV1 · existing integrations

Products

Contract approved · validation in progress

Create a product, parent, variant or component product.

Required permissions
{
  "anyOf": [
    {
      "allOf": [
        "products.write"
      ]
    }
  ]
}
Parameters
Idempotency-Key
header · Required
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.
Request
type
string · Required
["single","parent","variant","bundle","assembly","virtual"]
sku
string · Optional
name
string · Required
status
string · Optional
["active","inactive"]
description
string · Optional
barcode
string · Optional
upc
string · Optional
ean
string · Optional
gtin
string · Optional
brand
string · Optional
manufacturer
string · Optional
currency
string · Optional
salePrice
string · Optional
Non-negative decimal monetary amount as a string; never IEEE floating point.
trackInventory
boolean · Optional
parentId
string · Optional
Stable Shipbuy resource identifier serialized as a string. Treat as opaque; never confuse with a carrier identifier or display number.
variantOptions
array · Optional
variantSelection
object · Optional
Selected axis/value pairs. Axis names and values must belong to the parent options; the normalized combination is unique within the parent.
components
array · Optional
shippingDefaults
object · Optional
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 · Optional
metadata
object · Optional
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
}
Response
201Success.
400Malformed JSON, unsupported query or invalid request syntax.
401Missing, invalid, expired or revoked API key credential.
403Scope, 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.
404Resource absent or not visible in the authorized tenant/environment.
409Business conflict, changed idempotency payload, stale quote, pending side effect or insufficient stock/funds.
422Field/business validation failed; details identify invalid fields.
429Rate or paid-service limit exceeded. Respect Retry-After.
500Unexpected server error; use requestId and query operation before retrying a side effect.
503Service temporarily unavailable; upstream outcome may be unknown, query/replay the operation.
Download V2 contract (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.

Required permissions
{
  "anyOf": [
    {
      "allOf": [
        "products.read"
      ]
    }
  ]
}
Parameters
cursor
query · Optional
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 · Optional
integer
updatedAfter
query · Optional
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 · Optional
string
parentId
query · Optional
string
type
query · Optional
string
status
query · Optional
string
query
query · Optional
string
Response
200Success.
400Malformed JSON, unsupported query or invalid request syntax.
401Missing, invalid, expired or revoked API key credential.
403Scope, 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.
404Resource absent or not visible in the authorized tenant/environment.
409Business conflict, changed idempotency payload, stale quote, pending side effect or insufficient stock/funds.
422Field/business validation failed; details identify invalid fields.
429Rate or paid-service limit exceeded. Respect Retry-After.
500Unexpected server error; use requestId and query operation before retrying a side effect.
503Service temporarily unavailable; upstream outcome may be unknown, query/replay the operation.
Download V2 contract (JSON)

Retrieve a product with options and components.

Required permissions
{
  "anyOf": [
    {
      "allOf": [
        "products.read"
      ]
    }
  ]
}
Parameters
productId
path · Required
string
Response
200Success.
400Malformed JSON, unsupported query or invalid request syntax.
401Missing, invalid, expired or revoked API key credential.
403Scope, 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.
404Resource absent or not visible in the authorized tenant/environment.
409Business conflict, changed idempotency payload, stale quote, pending side effect or insufficient stock/funds.
422Field/business validation failed; details identify invalid fields.
429Rate or paid-service limit exceeded. Respect Retry-After.
500Unexpected server error; use requestId and query operation before retrying a side effect.
503Service temporarily unavailable; upstream outcome may be unknown, query/replay the operation.
Download V2 contract (JSON)

Edit or inactivate a product.

Required permissions
{
  "anyOf": [
    {
      "allOf": [
        "products.write"
      ]
    }
  ]
}
Parameters
productId
path · Required
string
Idempotency-Key
header · Required
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 · Required
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.
Request
sku
string · Optional
name
string · Optional
status
string · Optional
["active","inactive"]
description
string · Optional
barcode
string · Optional
upc
string · Optional
ean
string · Optional
gtin
string · Optional
brand
string · Optional
manufacturer
string · Optional
currency
string · Optional
salePrice
string · Optional
Non-negative decimal monetary amount as a string; never IEEE floating point.
trackInventory
boolean · Optional
parentId
string · Optional
Stable Shipbuy resource identifier serialized as a string. Treat as opaque; never confuse with a carrier identifier or display number.
variantOptions
array · Optional
variantSelection
object · Optional
Selected axis/value pairs. Axis names and values must belong to the parent options; the normalized combination is unique within the parent.
components
array · Optional
shippingDefaults
object · Optional
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 · Optional
metadata
object · Optional
Client-owned string metadata only. No secrets or card data. Not used for authorization or business rules.
{
  "status": "inactive"
}
Response
200Success.
400Malformed JSON, unsupported query or invalid request syntax.
401Missing, invalid, expired or revoked API key credential.
403Scope, 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.
404Resource absent or not visible in the authorized tenant/environment.
409Business conflict, changed idempotency payload, stale quote, pending side effect or insufficient stock/funds.
412If-Match does not match the current resource revision.
422Field/business validation failed; details identify invalid fields.
428Required concurrency precondition missing.
429Rate or paid-service limit exceeded. Respect Retry-After.
500Unexpected server error; use requestId and query operation before retrying a side effect.
503Service temporarily unavailable; upstream outcome may be unknown, query/replay the operation.
Download V2 contract (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.

Required permissions
{
  "anyOf": [
    {
      "allOf": [
        "products.write"
      ]
    }
  ]
}
Parameters
productId
path · Required
string
Idempotency-Key
header · Required
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.
Request
reason
string · Required
{
  "reason": "Product discontinued"
}
Response
200Success.
400Malformed JSON, unsupported query or invalid request syntax.
401Missing, invalid, expired or revoked API key credential.
403Scope, 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.
404Resource absent or not visible in the authorized tenant/environment.
409Business conflict, changed idempotency payload, stale quote, pending side effect or insufficient stock/funds.
422Field/business validation failed; details identify invalid fields.
429Rate or paid-service limit exceeded. Respect Retry-After.
500Unexpected server error; use requestId and query operation before retrying a side effect.
503Service temporarily unavailable; upstream outcome may be unknown, query/replay the operation.
Download V2 contract (JSON)