ShipBuy

API version
V2 · new integrationsV1 · existing integrations

Orders & fulfillment

Contract approved · validation in progress

Create an order through the normal ingest pipeline.

Required permissions
{
  "anyOf": [
    {
      "allOf": [
        "orders.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
externalId
string · Required
orderNumber
string · Optional
reference
string · Optional
currency
string · Required
shipTo
object · Required
Original address is preserved. Country-specific postal validation and carrier print-field limits are separate checks; do not silently truncate. Residential null means unknown.
shipFrom
object · Optional
Original address is preserved. Country-specific postal validation and carrier print-field limits are separate checks; do not silently truncate. Residential null means unknown.
warehouseId
string · Optional
Stable Shipbuy resource identifier serialized as a string. Treat as opaque; never confuse with a carrier identifier or display number.
deliveryMethod
string · Optional
["label","external","pickup"]
items
array · Required
shippingAmount
string · Optional
Non-negative decimal monetary amount as a string; never IEEE floating point.
taxAmount
string · Optional
Non-negative decimal monetary amount as a string; never IEEE floating point.
discountAmount
string · Optional
Non-negative decimal monetary amount as a string; never IEEE floating point.
note
string · Optional
metadata
object · Optional
Client-owned string metadata only. No secrets or card data. Not used for authorization or business rules.
{
  "externalId": "ERP-ORDER-1001",
  "orderNumber": "SO-1001",
  "currency": "USD",
  "shipTo": {
    "name": "Alex Chen",
    "street1": "456 Pine St",
    "city": "Seattle",
    "state": "WA",
    "postalCode": "98101",
    "country": "US",
    "phone": "2065550100",
    "residential": true
  },
  "warehouseId": "10",
  "deliveryMethod": "label",
  "items": [
    {
      "clientLineId": "line-1",
      "productId": "501",
      "quantity": 2,
      "unitPrice": "19.95"
    }
  ],
  "shippingAmount": "0.00",
  "taxAmount": "0.00",
  "discountAmount": "0.00"
}
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)

List sales orders.

Required permissions
{
  "anyOf": [
    {
      "allOf": [
        "orders.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.
reference
query · Optional
string
externalId
query · Optional
string
orderNumber
query · Optional
string
status
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 sales order.

Required permissions
{
  "anyOf": [
    {
      "allOf": [
        "orders.read"
      ]
    }
  ]
}
Parameters
orderId
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 allowed order fields.

Required permissions
{
  "anyOf": [
    {
      "allOf": [
        "orders.write"
      ]
    }
  ]
}
Parameters
orderId
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
reference
object · Optional
shipTo
object · Optional
Original address is preserved. Country-specific postal validation and carrier print-field limits are separate checks; do not silently truncate. Residential null means unknown.
note
string · Optional
items
array · Optional
metadata
object · Optional
Client-owned string metadata only. No secrets or card data. Not used for authorization or business rules.
{
  "reference": "PO-2026-1200",
  "note": "Customer requested side door delivery."
}
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)

Cancel an order with business guards.

Required permissions
{
  "anyOf": [
    {
      "allOf": [
        "orders.cancel"
      ]
    }
  ]
}
Parameters
orderId
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": "Customer canceled"
}
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)

Hold an order and eligible related fulfillments.

Required permissions
{
  "anyOf": [
    {
      "allOf": [
        "orders.write"
      ]
    }
  ]
}
Parameters
orderId
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
holdUntil
object · Optional
{
  "reason": "Customer address needs confirmation",
  "holdUntil": "2026-11-02 18:00:00"
}
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)

Uses the existing order release cascade only where the affected fulfillment hold is unambiguous. The current domain has no independent hold-source tracking. The public adapter must reject ambiguous shared-order/manual-hold release with 409 before mutation, not promise preservation or silently change shared hold semantics. No status rewind or inventory movement.

Required permissions
{
  "anyOf": [
    {
      "allOf": [
        "orders.write"
      ]
    }
  ]
}
Parameters
orderId
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": "Address confirmed"
}
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)

List fulfillments related to an order.

Required permissions
{
  "anyOf": [
    {
      "allOf": [
        "orders.read",
        "fulfillments.read"
      ]
    }
  ]
}
Parameters
orderId
path · Required
string
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.
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)

List fulfillment plans.

Required permissions
{
  "anyOf": [
    {
      "allOf": [
        "fulfillments.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.
warehouseId
query · Optional
string
orderId
query · Optional
string
status
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 fulfillment plan.

Required permissions
{
  "anyOf": [
    {
      "allOf": [
        "fulfillments.read"
      ]
    }
  ]
}
Parameters
fulfillmentId
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 a fulfillment shipping plan.

Required permissions
{
  "anyOf": [
    {
      "allOf": [
        "fulfillments.write"
      ]
    }
  ]
}
Parameters
fulfillmentId
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
warehouseId
string · Optional
Stable Shipbuy resource identifier serialized as a string. Treat as opaque; never confuse with a carrier identifier or display number.
shipFrom
object · Optional
Original address is preserved. Country-specific postal validation and carrier print-field limits are separate checks; do not silently truncate. Residential null means unknown.
shipTo
object · Optional
Original address is preserved. Country-specific postal validation and carrier print-field limits are separate checks; do not silently truncate. Residential null means unknown.
packages
array · Optional
options
object · Optional
Portable shipping options and optional typed FedEx Direct services. On fulfillment PATCH, omitted or null fields preserve their stored values; a supplied fedex object replaces the entire FedEx option group, and an empty object clears it. Carrier eligibility, account agreements and service combinations are validated before quoting or purchasing. Transportation billing is an atomic group: omit all four fields or use null to preserve it on PATCH; explicit sender clears the three billing details, while receiver or third_party requires all four fields together. Nonnull billing details without an external billingType are rejected. Duties and taxes remain independently configured under customs. Buying a frozen quote does not accept payer overrides.
customs
object · Optional
plannedShipDate
object · Optional
deliveryMethod
string · Optional
["label","external","pickup"]
{
  "packages": [
    {
      "packageNo": 1,
      "length": "12",
      "width": "9",
      "height": "3",
      "weight": "2",
      "dimensionUnit": "in",
      "weightUnit": "lb",
      "shape": "box"
    }
  ],
  "plannedShipDate": "2026-11-02"
}
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)

Quote the persisted fulfillment shipping plan.

Required permissions
{
  "anyOf": [
    {
      "allOf": [
        "rates.read",
        "fulfillments.read"
      ]
    }
  ]
}
Parameters
fulfillmentId
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
expectedVersion
string · Required
Opaque resource revision. The ETag header is its quoted representation; send the exact ETag as If-Match.
shippingAccountIds
array · Optional
serviceCodes
array · Optional
{
  "expectedVersion": "7",
  "shippingAccountIds": [
    "41"
  ]
}
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)

Uses the existing inventory-aware shared ship transition and current account trigger. Does not buy labels; label purchase may already have auto-shipped under account settings, in which case idempotent state guards apply. Reject unsupported partial/dropship handling explicitly.

Required permissions
{
  "anyOf": [
    {
      "allOf": [
        "fulfillments.ship"
      ]
    }
  ]
}
Parameters
fulfillmentId
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.
{
  "mode": "label",
  "expectedVersion": "8"
}
Response
200Success.
202Accepted; poll Location or GET /operations/{id}.
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)

Split unexecuted quantities into a new fulfillment.

Required permissions
{
  "anyOf": [
    {
      "allOf": [
        "fulfillments.write"
      ]
    }
  ]
}
Parameters
fulfillmentId
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
expectedVersion
string · Required
Opaque resource revision. The ETag header is its quoted representation; send the exact ETag as If-Match.
items
array · Required
{
  "expectedVersion": "4",
  "items": [
    {
      "fulfillmentItemId": "601",
      "moveQuantity": 1
    }
  ]
}
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)