CanopyDocs
Reference

Shipping

Create a shipping label

POST
/api/shipping/labels

Tenant-wide credentials only. A credential pinned to one client is refused (403), as that client's portal users are; use a tenant-wide credential with X-Client-Id.

Authorization

oauth2 shipping:write
AuthorizationBearer <token>

OAuth2 client-credentials grant.

In: header

Scope: shipping:write

Header Parameters

Idempotency-Key?string

Optional client-supplied key that makes this write safe to retry. A replay of a completed key returns the original response; an in-flight duplicate gets 409. A key is bound to the operation — method, URL and request body — and to the caller — the credential and its token scopes; reusing it with any of those changed gets 422.

Lengthlength <= 255

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/shipping/labels" \  -H "Content-Type: application/json" \  -d '{    "orderId": "string"  }'
{  "success": true,  "data": {    "id": "string",    "clientId": "string",    "orderId": "string",    "packRecordId": "string",    "shipCode": "string",    "mode": "PARCEL",    "bolNumber": "string",    "proNumber": "string",    "bolUrl": "string",    "isReturn": true,    "carrierService": "string",    "trackingNumber": "string",    "trackingUrl": "string",    "canEditTracking": true,    "canMarkShipped": true,    "labelUrl": "string",    "labelFormat": "string",    "shippingCost": 0,    "rate": 0,    "tax": 0,    "totalPaid": 0,    "weight": 0,    "dimensions": {      "length": 0,      "width": 0,      "height": 0    },    "shipDate": "2019-08-24T14:15:22Z",    "status": "LABEL_CREATED",    "signatureRequested": "STANDARD",    "insuredValue": 0,    "insuredCurrency": "string",    "voidedAt": "2019-08-24T14:15:22Z",    "deliveredAt": "2019-08-24T14:15:22Z",    "statusVoteRetiredAt": "2019-08-24T14:15:22Z",    "createdAt": "2019-08-24T14:15:22Z",    "orderNumber": "string",    "customerName": "string",    "shippingMethod": "string",    "orderCreatedAt": "2019-08-24T14:15:22Z",    "orderTotalAmount": 0,    "shippingAddressCity": "string",    "shippingAddressState": "string",    "shippingAddressZip": "string",    "shippingAddressCountry": "string",    "orderCurrency": "string",    "orderShippingAmount": 0,    "costOwner": "TENANT",    "clientCurrency": "string",    "packRecordTotalItems": 0,    "packerName": "string",    "carrierCode": "string",    "boxName": "string",    "labelData": "string"  }}

List shipments

GET
/api/shipping/shipments

Order-money fields (orderTotalAmount, orderShippingAmount, discounts) are null for tokens without orders:read.

Authorization

oauth2 shipping:read
AuthorizationBearer <token>

OAuth2 client-credentials grant.

In: header

Scope: shipping:read

Query Parameters

page?integer
Range0 < value
Default1
limit?integer
Range0 < value <= 500
Default20
search?string
Lengthlength <= 100
sortBy?string
Lengthlength <= 50
sortOrder?string
Default"asc"

Value in

  • "asc"
  • "desc"
status?string
orderId?string
trackingNumber?string
dateFrom?string
dateTo?string
shippedFrom?string

Inclusive ship-date timestamp. Preserves the exact instant.

Formatdate-time
shippedBefore?string

Exclusive ship-date timestamp. Does not expand to the end of the day.

Formatdate-time
attention?string

Value in

  • "AWAITING_SCAN"
  • "STALLED"
  • "EXCEPTION"
  • "NOT_RECENTLY_CHECKED"
  • "RETURNED_TO_SENDER"
carriers?string
methods?string
q?string
includeVoided?string

Value in

  • "true"
  • "false"
updatedSince?string
Formatdate-time

Header Parameters

X-Client-Id?string

Scope results to one client (brand). Resolve a client name to its id via GET /api/clients/lookup. Validated against the credential's tenant; ignored by a client-pinned credential.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/shipping/shipments"
{  "success": true,  "data": [    {      "id": "string",      "clientId": "string",      "orderId": "string",      "packRecordId": "string",      "shipCode": "string",      "mode": "PARCEL",      "bolNumber": "string",      "proNumber": "string",      "bolUrl": "string",      "isReturn": true,      "carrierService": "string",      "trackingNumber": "string",      "trackingUrl": "string",      "canEditTracking": true,      "canMarkShipped": true,      "labelUrl": "string",      "labelFormat": "string",      "shippingCost": 0,      "rate": 0,      "tax": 0,      "totalPaid": 0,      "weight": 0,      "dimensions": {        "length": 0,        "width": 0,        "height": 0      },      "shipDate": "2019-08-24T14:15:22Z",      "status": "LABEL_CREATED",      "signatureRequested": "STANDARD",      "insuredValue": 0,      "insuredCurrency": "string",      "voidedAt": "2019-08-24T14:15:22Z",      "deliveredAt": "2019-08-24T14:15:22Z",      "statusVoteRetiredAt": "2019-08-24T14:15:22Z",      "createdAt": "2019-08-24T14:15:22Z",      "orderNumber": "string",      "customerName": "string",      "shippingMethod": "string",      "orderCreatedAt": "2019-08-24T14:15:22Z",      "orderTotalAmount": 0,      "shippingAddressCity": "string",      "shippingAddressState": "string",      "shippingAddressZip": "string",      "shippingAddressCountry": "string",      "orderCurrency": "string",      "orderShippingAmount": 0,      "costOwner": "TENANT",      "clientCurrency": "string",      "packRecordTotalItems": 0,      "packerName": "string",      "carrierCode": "string",      "boxName": "string",      "orderSplitFrom": {        "id": "string",        "orderNumber": "string"      },      "clientName": "string",      "warehouseName": "string",      "orderDistinctLines": 0,      "orderDiscountTotal": 0,      "orderDiscountedLineTotal": 0,      "lotNumbers": [        "string"      ],      "lotExpiresAt": "2019-08-24T14:15:22Z",      "carrierScanned": true,      "lines": [        {          "orderLineId": "string",          "skuId": "string",          "quantity": 0,          "supersededQuantity": 0        }      ],      "outboundSync": {        "status": "PENDING",        "attempts": 0,        "lastError": "string",        "lastAttemptAt": "2019-08-24T14:15:22Z",        "nextRunAt": "2019-08-24T14:15:22Z"      }    }  ],  "pagination": {    "page": 0,    "limit": 0,    "total": 0,    "totalPages": 0  }}

Shipments summary

GET
/api/shipping/shipments/summary

Authorization

oauth2 shipping:read
AuthorizationBearer <token>

OAuth2 client-credentials grant.

In: header

Scope: shipping:read

Query Parameters

status?string
orderId?string
trackingNumber?string
dateFrom?string
dateTo?string
shippedFrom?string

Inclusive ship-date timestamp. Preserves the exact instant.

Formatdate-time
shippedBefore?string

Exclusive ship-date timestamp. Does not expand to the end of the day.

Formatdate-time
carriers?string
methods?string
q?string
includeVoided?string

Value in

  • "true"
  • "false"

Header Parameters

X-Client-Id?string

Scope results to one client (brand). Resolve a client name to its id via GET /api/clients/lookup. Validated against the credential's tenant; ignored by a client-pinned credential.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/shipping/shipments/summary"
{  "success": true,  "data": {    "totalShipments": 0,    "totalItems": 0,    "distinctItems": 0,    "totalShippingCost": 0,    "perCurrency": [      {        "currency": "string",        "labelCostTotal": 0,        "customerShippingTotal": 0,        "profit": 0      }    ],    "mixedCurrencyShipments": 0  }}

Delayed-shipment counts

GET
/api/shipping/shipments/attention

In-flight parcels that have stopped moving, bucketed: AWAITING_SCAN (label bought, no custody scan in 72h), STALLED (in transit, no scan for 4 days), EXCEPTION (carrier reported a problem) and NOT_RECENTLY_CHECKED (our tracking poller is behind, so the silence may be ours). Those buckets are mutually exclusive subsets of inFlight; return labels are excluded. RETURNED_TO_SENDER (the carrier sent the parcel back and no RTS return has been opened for it) overlaps them — it is a to-do, not a status slice. Pair with ?attention= on GET /api/shipping/shipments for the rows.

Authorization

oauth2 shipping:read
AuthorizationBearer <token>

OAuth2 client-credentials grant.

In: header

Scope: shipping:read

Header Parameters

X-Client-Id?string

Scope results to one client (brand). Resolve a client name to its id via GET /api/clients/lookup. Validated against the credential's tenant; ignored by a client-pinned credential.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/shipping/shipments/attention"
{  "success": true,  "data": {    "inFlight": 0,    "awaitingScan": 0,    "stalled": 0,    "exception": 0,    "notRecentlyChecked": 0,    "returnedToSender": 0,    "thresholds": {      "awaitingScanHours": 0,      "stalledDays": 0    }  }}

Get a shipment

GET
/api/shipping/shipments/{id}

Includes the stored tracking timeline (tracking.source = STORED) or, when none is stored yet, a live carrier lookup (CARRIER). Generic labels return null tracking without contacting a carrier.

Authorization

oauth2 shipping:read
AuthorizationBearer <token>

OAuth2 client-credentials grant.

In: header

Scope: shipping:read

Path Parameters

id*string

Shipment id

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/shipping/shipments/string"
{  "success": true,  "data": {    "id": "string",    "clientId": "string",    "orderId": "string",    "packRecordId": "string",    "shipCode": "string",    "mode": "PARCEL",    "bolNumber": "string",    "proNumber": "string",    "bolUrl": "string",    "isReturn": true,    "carrierService": "string",    "trackingNumber": "string",    "trackingUrl": "string",    "canEditTracking": true,    "canMarkShipped": true,    "labelUrl": "string",    "labelFormat": "string",    "shippingCost": 0,    "rate": 0,    "tax": 0,    "totalPaid": 0,    "weight": 0,    "dimensions": {      "length": 0,      "width": 0,      "height": 0    },    "shipDate": "2019-08-24T14:15:22Z",    "status": "LABEL_CREATED",    "signatureRequested": "STANDARD",    "insuredValue": 0,    "insuredCurrency": "string",    "voidedAt": "2019-08-24T14:15:22Z",    "deliveredAt": "2019-08-24T14:15:22Z",    "statusVoteRetiredAt": "2019-08-24T14:15:22Z",    "createdAt": "2019-08-24T14:15:22Z",    "orderNumber": "string",    "customerName": "string",    "shippingMethod": "string",    "orderCreatedAt": "2019-08-24T14:15:22Z",    "orderTotalAmount": 0,    "shippingAddressCity": "string",    "shippingAddressState": "string",    "shippingAddressZip": "string",    "shippingAddressCountry": "string",    "orderCurrency": "string",    "orderShippingAmount": 0,    "costOwner": "TENANT",    "clientCurrency": "string",    "packRecordTotalItems": 0,    "packerName": "string",    "carrierCode": "string",    "boxName": "string",    "labelData": "string",    "lines": [      {        "orderLineId": "string",        "skuId": "string",        "quantity": 0,        "supersededQuantity": 0      }    ],    "tracking": {      "status": "PRE_TRANSIT",      "rawStatus": "string",      "events": [        {          "status": "PRE_TRANSIT",          "rawStatus": "string",          "description": "string",          "location": "string",          "timestamp": "2019-08-24T14:15:22Z",          "carrier": "string"        }      ],      "source": "STORED",      "lastCheckedAt": "2019-08-24T14:15:22Z",      "details": {        "destination": "string",        "url": "string",        "carrierPhone": "string"      }    },    "outboundSync": {      "status": "PENDING",      "attempts": 0,      "lastError": "string",      "lastAttemptAt": "2019-08-24T14:15:22Z",      "nextRunAt": "2019-08-24T14:15:22Z"    }  }}

List shipped items

GET
/api/shipping/shipped-items

One row per packed line. unitPrice, shippedSubtotal, tariffCode and customer contact fields are null for tokens without orders:read.

Authorization

oauth2 shipping:read
AuthorizationBearer <token>

OAuth2 client-credentials grant.

In: header

Scope: shipping:read

Query Parameters

page?integer
Range0 < value
Default1
limit?integer
Range0 < value <= 500
Default20
search?string
Lengthlength <= 100
sortBy?string
Lengthlength <= 50
sortOrder?string
Default"asc"

Value in

  • "asc"
  • "desc"
orderId?string
skuId?string
carriers?string
methods?string
dateFrom?string
dateTo?string
q?string
includeVoided?string

Value in

  • "true"
  • "false"

Header Parameters

X-Client-Id?string

Scope results to one client (brand). Resolve a client name to its id via GET /api/clients/lookup. Validated against the credential's tenant; ignored by a client-pinned credential.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/shipping/shipped-items"
{  "success": true,  "data": [    {      "id": "string",      "packRecordId": "string",      "orderId": "string",      "orderLineId": "string",      "skuId": "string",      "createdAt": "2019-08-24T14:15:22Z",      "orderCreatedAt": "2019-08-24T14:15:22Z",      "skuCode": "string",      "productName": "string",      "tariffCode": "string",      "quantityOrdered": 0,      "quantityShipped": 0,      "unitPrice": 0,      "shippedSubtotal": 0,      "orderNumber": "string",      "channelName": "string",      "warehouseName": "string",      "shippingMethod": "string",      "orderTags": [        "string"      ],      "customerName": "string",      "customerEmail": "string",      "customerPhone": "string",      "shippingAddressLine1": "string",      "shippingAddressLine2": "string",      "shippingAddressCity": "string",      "shippingAddressState": "string",      "shippingAddressZip": "string",      "shippingAddressCountry": "string",      "shippingAddressCompany": "string",      "shipmentId": "string",      "trackingNumber": "string",      "carrierService": "string",      "labelUrl": "string",      "shippingCost": 0,      "shipmentStatus": "LABEL_CREATED",      "binLabel": "string",      "packerName": "string"    }  ],  "pagination": {    "page": 0,    "limit": 0,    "total": 0,    "totalPages": 0  }}

Shipped items summary

GET
/api/shipping/shipped-items/summary

Authorization

oauth2 shipping:read
AuthorizationBearer <token>

OAuth2 client-credentials grant.

In: header

Scope: shipping:read

Query Parameters

orderId?string
skuId?string
carriers?string
methods?string
dateFrom?string
dateTo?string
q?string
includeVoided?string

Value in

  • "true"
  • "false"

Header Parameters

X-Client-Id?string

Scope results to one client (brand). Resolve a client name to its id via GET /api/clients/lookup. Validated against the credential's tenant; ignored by a client-pinned credential.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/shipping/shipped-items/summary"
{  "success": true,  "data": {    "totalShippedItems": 0,    "totalQuantity": 0,    "totalShippedSubtotal": 0,    "distinctSkus": 0,    "distinctOrders": 0,    "totalShippingCost": 0  }}

Void a shipment / label

POST
/api/shipping/shipments/{id}/void

Tenant-wide credentials only. A credential pinned to one client is refused (403), as that client's portal users are; use a tenant-wide credential with X-Client-Id.

Authorization

oauth2 shipping:write
AuthorizationBearer <token>

OAuth2 client-credentials grant.

In: header

Scope: shipping:write

Path Parameters

id*string

Shipment id

Header Parameters

Idempotency-Key?string

Optional client-supplied key that makes this write safe to retry. A replay of a completed key returns the original response; an in-flight duplicate gets 409. A key is bound to the operation — method, URL and request body — and to the caller — the credential and its token scopes; reusing it with any of those changed gets 422.

Lengthlength <= 255

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/shipping/shipments/string/void"
{  "success": true,  "data": {    "id": "string",    "clientId": "string",    "orderId": "string",    "packRecordId": "string",    "shipCode": "string",    "mode": "PARCEL",    "bolNumber": "string",    "proNumber": "string",    "bolUrl": "string",    "isReturn": true,    "carrierService": "string",    "trackingNumber": "string",    "trackingUrl": "string",    "canEditTracking": true,    "canMarkShipped": true,    "labelUrl": "string",    "labelFormat": "string",    "shippingCost": 0,    "rate": 0,    "tax": 0,    "totalPaid": 0,    "weight": 0,    "dimensions": {      "length": 0,      "width": 0,      "height": 0    },    "shipDate": "2019-08-24T14:15:22Z",    "status": "VOIDED",    "signatureRequested": "STANDARD",    "insuredValue": 0,    "insuredCurrency": "string",    "voidedAt": "2019-08-24T14:15:22Z",    "deliveredAt": "2019-08-24T14:15:22Z",    "statusVoteRetiredAt": "2019-08-24T14:15:22Z",    "createdAt": "2019-08-24T14:15:22Z",    "orderNumber": "string",    "customerName": "string",    "shippingMethod": "string",    "orderCreatedAt": "2019-08-24T14:15:22Z",    "orderTotalAmount": 0,    "shippingAddressCity": "string",    "shippingAddressState": "string",    "shippingAddressZip": "string",    "shippingAddressCountry": "string",    "orderCurrency": "string",    "orderShippingAmount": 0,    "costOwner": "TENANT",    "clientCurrency": "string",    "packRecordTotalItems": 0,    "packerName": "string",    "carrierCode": "string",    "boxName": "string"  }}

Update generic shipment tracking

PATCH
/api/shipping/shipments/{id}/tracking

Tenant-wide credentials only. A credential pinned to one client is refused (403), as that client's portal users are; use a tenant-wide credential with X-Client-Id. Add, correct or clear tracking on an active outbound Generic Label parcel after packing is completed. Send the current tracking values as expectedTrackingNumber and expectedTrackingUrl; a stale update returns 409. To clear tracking, send an empty trackingNumber and null trackingUrl — but on a sales channel order a number already attached cannot be removed (409), and can be corrected only where the channel updates an existing fulfillment (409 otherwise). No postage is bought and no carrier is contacted, but the write is not always local: on a sales channel order a new, non-empty number queues a push that creates — or, where the channel supports it, corrects — the fulfillment on the storefront, which by default emails the customer a shipping confirmation. A URL-only edit, a re-save of the same number, and clearing never push. If the order is waiting at FULFILLED, saving a new number also advances it to SHIPPED — on any order, channel or not — which emits the order.shipped webhook and, on a sales channel with them switched on, queues archive-on-ship and capture-on-ship (both off by default; capture charges the customer). A parcel that has lost its say over the order's status — superseded by a reship, or retired when a partial shipment closed out — records its tracking without shipping the order. Order money fields are null for tokens without orders:read.

Authorization

oauth2 shipping:write
AuthorizationBearer <token>

OAuth2 client-credentials grant.

In: header

Scope: shipping:write

Path Parameters

id*string

Shipment id

Header Parameters

Idempotency-Key?string

Optional client-supplied key that makes this write safe to retry. A replay of a completed key returns the original response; an in-flight duplicate gets 409. A key is bound to the operation — method, URL and request body — and to the caller — the credential and its token scopes; reusing it with any of those changed gets 422.

Lengthlength <= 255

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://example.com/api/shipping/shipments/string/tracking" \  -H "Content-Type: application/json" \  -d '{    "trackingNumber": "string",    "trackingUrl": "http://example.com",    "expectedTrackingNumber": "string",    "expectedTrackingUrl": "string"  }'
{  "success": true,  "data": {    "id": "string",    "clientId": "string",    "orderId": "string",    "packRecordId": "string",    "shipCode": "string",    "mode": "PARCEL",    "bolNumber": "string",    "proNumber": "string",    "bolUrl": "string",    "isReturn": true,    "carrierService": "string",    "trackingNumber": "string",    "trackingUrl": "string",    "canEditTracking": true,    "canMarkShipped": true,    "labelUrl": "string",    "labelFormat": "string",    "shippingCost": 0,    "rate": 0,    "tax": 0,    "totalPaid": 0,    "weight": 0,    "dimensions": {      "length": 0,      "width": 0,      "height": 0    },    "shipDate": "2019-08-24T14:15:22Z",    "status": "LABEL_CREATED",    "signatureRequested": "STANDARD",    "insuredValue": 0,    "insuredCurrency": "string",    "voidedAt": "2019-08-24T14:15:22Z",    "deliveredAt": "2019-08-24T14:15:22Z",    "statusVoteRetiredAt": "2019-08-24T14:15:22Z",    "createdAt": "2019-08-24T14:15:22Z",    "orderNumber": "string",    "customerName": "string",    "shippingMethod": "string",    "orderCreatedAt": "2019-08-24T14:15:22Z",    "orderTotalAmount": 0,    "shippingAddressCity": "string",    "shippingAddressState": "string",    "shippingAddressZip": "string",    "shippingAddressCountry": "string",    "orderCurrency": "string",    "orderShippingAmount": 0,    "costOwner": "TENANT",    "clientCurrency": "string",    "packRecordTotalItems": 0,    "packerName": "string",    "carrierCode": "string",    "boxName": "string"  }}

Get carrier tracking status

GET
/api/shipping/shipments/{id}/track

A live carrier lookup on every call for carrier labels. Generic labels return UNKNOWN, the stored shipment status as rawStatus, and no events without contacting a carrier. For the stored timeline use GET /api/shipping/shipments/{id}.

Authorization

oauth2 shipping:read
AuthorizationBearer <token>

OAuth2 client-credentials grant.

In: header

Scope: shipping:read

Path Parameters

id*string

Shipment id

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/shipping/shipments/string/track"
{  "success": true,  "data": {    "status": "PRE_TRANSIT",    "rawStatus": "string",    "events": [      {        "status": "PRE_TRANSIT",        "rawStatus": "string",        "description": "string",        "location": "string",        "timestamp": "2019-08-24T14:15:22Z",        "carrier": "string",        "externalEventId": "string"      }    ],    "details": {      "shipCode": "string",      "destination": "string",      "url": "string",      "carrierPhone": "string"    }  }}

List shipping services

GET
/api/shipping/services

Available carrier services and the internal Generic Label option; pass a service token as postageType on POST /api/shipping/labels. Generic labels are generated in Canopy without a carrier purchase.

Authorization

oauth2 shipping:read
AuthorizationBearer <token>

OAuth2 client-credentials grant.

In: header

Scope: shipping:read

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/shipping/services"
{  "success": true,  "data": [    {      "carrierAccountId": "string",      "carrier": "string",      "nickname": "string",      "services": [        {          "token": "string",          "label": "string",          "trackable": true        }      ],      "capabilities": {        "signature": "NONE",        "insurance": "NONE",        "insuranceCost": "ITEMIZED",        "multiParcel": false,        "ltl": false      },      "isPurchaseDefault": true,      "needsReconnect": true    }  ]}

Inventory

Previous Page

Receiving

Next Page