Shipping

Only accounts allowed by the authenticated integration, environment and tenant. Includes customer-facing services/packaging capabilities; never internal credentials or provider cost.

Required permissions

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

Parameters

Response

The implementation being validated supports standalone shipping in USD only. fulfillment and order_fulfillment sources, and nonzero insuredValue, return unsupported_capability until those capabilities are available.

source is exactly one of standalone, fulfillment or an explicit order+fulfillment association. All source resource IDs and shipping accounts must fit the integration scope. Fulfillment sources additionally require fulfillments.read (order_fulfillment also orders.read). Result may contain partial carrier failures; each returned rate covers all packages.

Required permissions

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

{
  "source.kind=fulfillment": [
    "fulfillments.read"
  ],
  "source.kind=order_fulfillment": [
    "orders.read",
    "fulfillments.read"
  ]
}

Parameters

Request

{
  "source": {
    "kind": "standalone",
    "shipping": {
      "shipFrom": {
        "name": "Warehouse",
        "street1": "123 Market St",
        "city": "San Francisco",
        "state": "CA",
        "postalCode": "94103",
        "country": "US",
        "phone": "4155550100",
        "residential": false
      },
      "shipTo": {
        "name": "Alex Chen",
        "street1": "456 Pine St",
        "city": "Seattle",
        "state": "WA",
        "postalCode": "98101",
        "country": "US",
        "phone": "2065550100",
        "residential": true
      },
      "packages": [
        {
          "packageNo": 1,
          "length": "12",
          "width": "9",
          "height": "3",
          "weight": "2",
          "dimensionUnit": "in",
          "weightUnit": "lb",
          "shape": "box"
        }
      ],
      "reference": "ERP-SHIP-1001"
    }
  },
  "shippingAccountIds": [
    "41"
  ]
}

Response

The implementation being validated purchases standalone quotes only. Fulfillment-bound purchases and insured shipments remain unavailable until their corresponding integrations are implemented and verified.

Server validates immutable quote binding, expiry, current permissions, fulfillment version/readiness, policy, wallet and carrier capability before purchase. A fulfillment-origin purchase additionally requires fulfillments.write. If the current account mark_shipped_trigger or another existing business rule will automatically confirm shipment/decrement inventory, fulfillments.ship is also required before ANY carrier call; absent permission returns 403, never skips that side effect or implicitly grants it from labels.buy. One purchase produces a shipment with one or more packages. Each frozen quote binds durably to one purchase operation before the carrier call; changing the Idempotency-Key or selecting another rate from that quote cannot start another purchase. Quote expiry does not release that binding; a different purchase request remains operation_pending. Retry the original key to recover its operation/result. An intentional new shipment requires a new quote and a new key; do not create a replacement quote to retry an unknown purchase. Unknown carrier outcome is needs_review, never automatically a second purchase.

Required permissions

{
  "anyOf": [
    {
      "allOf": [
        "labels.buy"
      ]
    }
  ]
}

{
  "quote.source.kind in [fulfillment,order_fulfillment]": [
    "fulfillments.write"
  ],
  "existing_business_rule_will_auto_ship": [
    "fulfillments.ship"
  ]
}

Parameters

Request

{
  "quoteId": "quote_301",
  "rateId": "rate_302",
  "reference": "ERP-SHIP-1001"
}

Response

List visible shipments.

Required permissions

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

Parameters

Response

Retrieve a shipment and all packages.

Required permissions

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

Parameters

Response

Returns persisted valid documents with refreshed signed URLs, including after an original purchase response was lost. Historical voided-label access is visibly marked by the owning shipment/package status; never suggests it is valid for shipping.

Required permissions

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

Parameters

Response

Package subset is explicit; whole-shipment providers reject subsets. Void acceptance, label lifecycle and wallet/carrier refund completion are distinct. Refund cannot exceed actual collected amounts. Partial successes are durable and replayable; no rollback claim for already completed carrier actions. A fulfillment-linked void additionally requires fulfillments.write. If existing rules can revert shipment and restore inventory/reservations, fulfillments.ship is also required before the carrier call. Missing authority returns 403; never skip the existing reversal rules or silently broaden labels.void into inventory authority.

Required permissions

{
  "anyOf": [
    {
      "allOf": [
        "labels.void"
      ]
    }
  ]
}

{
  "shipment_has_fulfillment": [
    "fulfillments.write"
  ],
  "existing_business_rule_may_revert_shipment": [
    "fulfillments.ship"
  ]
}

Parameters

Request

{
  "reason": "Customer canceled before handover"
}

Response

Cached tracking for an authorized package. Included basic tracking for Shipbuy-purchased labels does not create a paid external tracker. No immediate upstream call is caused by repeated reads.

Required permissions

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

Parameters

Response

Register an external tracking number. Commercial gate: new live actions are disabled until the service price and quota policy are confirmed. Return 403/service_not_enabled before any upstream call, new fee or accrued amount; never silently execute for free. This is independent of the API key scope check. Test simulation and authorized completed-idempotency replay remain available without new charges. No public product-enablement API is provided.

Required permissions

{
  "anyOf": [
    {
      "allOf": [
        "tracking.subscribe"
      ]
    }
  ]
}

Parameters

Request

{
  "carrier": "ups",
  "trackingNumber": "1Z999AA10123456784",
  "shipDate": "2026-11-01",
  "reference": "EXTERNAL-1001"
}

Response

List external tracking registrations.

Required permissions

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

Parameters

Response

Retrieve an external tracker and history.

Required permissions

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

Parameters

Response

Preflight shipments eligible for a manifest. Determine the ship date from persisted shipping options.shipDate first, then shippedAt. An unknown or mismatched date returns eligible=false with an issue; never infer the ship date from label creation time.

Required permissions

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

Parameters

Response

Create one manifest for a compatible shipment group.

Required permissions

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

Parameters

Request

{
  "shipmentIds": [
    "301",
    "302"
  ],
  "shipDate": "2026-11-01"
}

Response

List manifests.

Required permissions

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

Parameters

Response

Retrieve a manifest and recovery state.

Required permissions

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

Parameters

Response

Retrieve manifest PDF links.

Required permissions

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

Parameters

Response

Only local membership release; does not void the carrier document. Unknown/partial/document-failed results remain occupied and return 409 until reconciliation. Must not be presented as carrier cancellation.

Required permissions

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

Parameters

Request

{
  "reason": "Reorganize local manifest group"
}

Response

Verify a postal address without changing saved records. Commercial gate: new live actions are disabled until the service price and quota policy are confirmed. Return 403/service_not_enabled before any upstream call, new fee or accrued amount; never silently execute for free. This is independent of the API key scope check. Test simulation and authorized completed-idempotency replay remain available without new charges. No public product-enablement API is provided.

Required permissions

{
  "anyOf": [
    {
      "allOf": [
        "addresses.verify"
      ]
    }
  ]
}

Parameters

Request

{
  "address": {
    "name": "Alex Chen",
    "street1": "456 Pine St",
    "city": "Seattle",
    "state": "WA",
    "postalCode": "98101",
    "country": "US",
    "phone": "2065550100",
    "residential": true
  }
}

Response

Authorization must match this operation type (purchase:labels.buy; void:labels.void; manifest:manifests.write; ship:fulfillments.ship), integration identity and resource restrictions. Possessing a different listed scope does not grant access. Completed label purchases remain recoverable after response loss; documents may carry freshly signed links.

Required permissions

{
  "anyOf": [
    {
      "allOf": [
        "labels.buy"
      ]
    },
    {
      "allOf": [
        "labels.void"
      ]
    },
    {
      "allOf": [
        "manifests.write"
      ]
    },
    {
      "allOf": [
        "fulfillments.ship"
      ]
    }
  ]
}

Parameters

Response