CanopyDocs
Reference

Receiving

List inbound shipments

GET
/api/receiving/shipments

Authorization

oauth2 receiving:read
AuthorizationBearer <token>

OAuth2 client-credentials grant.

In: header

Scope: receiving: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
dateFrom?string
dateTo?string
vendorName?string
externalPo?string
shipmentNumber?string
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/receiving/shipments"
{  "success": true,  "data": [    {      "id": "string",      "clientId": "string",      "clientName": "string",      "clientCode": "string",      "warehouseId": "string",      "warehouseName": "string",      "shipmentNumber": "string",      "externalPoNumber": "string",      "status": "PENDING",      "expectedArrival": "2019-08-24T14:15:22Z",      "vendorName": "string",      "trackingNumber": "string",      "expectedPallets": 0,      "expectedCartons": 0,      "receivedPallets": 0,      "receivedCartons": 0,      "notes": "string",      "receivedBy": {        "id": "string",        "firstName": "string",        "lastName": "string",        "email": "string"      },      "createdBy": {        "id": "string",        "firstName": "string",        "lastName": "string",        "email": "string"      },      "lineCount": 0,      "totalExpected": 0,      "totalReceived": 0,      "totalDamaged": 0,      "totalRejected": 0,      "isActive": true,      "createdAt": "2019-08-24T14:15:22Z",      "updatedAt": "2019-08-24T14:15:22Z"    }  ],  "pagination": {    "page": 0,    "limit": 0,    "total": 0,    "totalPages": 0  }}

Create an inbound shipment (PO)

POST
/api/receiving/shipments

Idempotent on your externalPoNumber when supplied: a repeat returns the existing PO. The response is the PO header only — read GET /api/receiving/shipments/{id} for its lines. A line may carry sellAheadQuantity (0 ≤ n ≤ expectedQuantity): units to advertise to the client's opted-in sales channels before the goods arrive; orders for them wait as backorders until the PO is received. Rejected unless sell ahead is enabled for the client. With neither warehouseId nor an X-Warehouse-Id header, the PO is recorded at the client's default warehouse; with no default, only a tenant with a single warehouse can omit both.

Authorization

oauth2 receiving:write
AuthorizationBearer <token>

OAuth2 client-credentials grant.

In: header

Scope: receiving: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/receiving/shipments" \  -H "Content-Type: application/json" \  -d '{    "lines": [      {        "skuId": "string",        "expectedQuantity": 1      }    ]  }'
{  "success": true,  "data": {    "id": "string",    "clientId": "string",    "clientName": "string",    "clientCode": "string",    "warehouseId": "string",    "warehouseName": "string",    "shipmentNumber": "string",    "externalPoNumber": "string",    "status": "PENDING",    "expectedArrival": "2019-08-24T14:15:22Z",    "vendorName": "string",    "trackingNumber": "string",    "expectedPallets": 0,    "expectedCartons": 0,    "receivedPallets": 0,    "receivedCartons": 0,    "notes": "string",    "receivedBy": {      "id": "string",      "firstName": "string",      "lastName": "string",      "email": "string"    },    "createdBy": {      "id": "string",      "firstName": "string",      "lastName": "string",      "email": "string"    },    "lineCount": 0,    "totalExpected": 0,    "totalReceived": 0,    "totalDamaged": 0,    "totalRejected": 0,    "isActive": true,    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z"  }}

Overdue POs and receiving discrepancies

GET
/api/receiving/shipments/attention

overdue (open POs past their expected arrival, with daysOverdue and a NOT_ARRIVED / PART_RECEIVED / RECEIVING_STALLED diagnosis), undated (open POs with no ETA at all) and discrepancies (recently completed POs whose units did not match). Unit columns are separate buckets: receivedQuantity is good units only, damagedQuantity was quarantined, rejectedQuantity was refused — missingUnits is what the vendor never delivered.

Authorization

oauth2 receiving:read
AuthorizationBearer <token>

OAuth2 client-credentials grant.

In: header

Scope: receiving:read

Query Parameters

limit?integer

Rows per bucket.

Range1 <= value <= 100
Default25
days?integer

Discrepancy look-back window.

Range1 <= value <= 180
Default30

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/receiving/shipments/attention"
{  "success": true,  "data": {    "overdue": [      {        "id": "string",        "shipmentNumber": "string",        "externalPoNumber": "string",        "vendorName": "string",        "status": "PENDING",        "clientName": "string",        "warehouseName": "string",        "expectedArrival": "2019-08-24T14:15:22Z",        "createdAt": "2019-08-24T14:15:22Z",        "daysOverdue": 0,        "expectedUnits": 0,        "receivedUnits": 0,        "damagedUnits": 0,        "rejectedUnits": 0,        "outstandingUnits": 0,        "lastReceiptAt": "2019-08-24T14:15:22Z",        "diagnosis": "NOT_ARRIVED"      }    ],    "undated": [      {        "id": "string",        "shipmentNumber": "string",        "externalPoNumber": "string",        "vendorName": "string",        "status": "PENDING",        "clientName": "string",        "warehouseName": "string",        "expectedArrival": "2019-08-24T14:15:22Z",        "createdAt": "2019-08-24T14:15:22Z",        "daysOverdue": 0,        "expectedUnits": 0,        "receivedUnits": 0,        "damagedUnits": 0,        "rejectedUnits": 0,        "outstandingUnits": 0,        "lastReceiptAt": "2019-08-24T14:15:22Z",        "diagnosis": "NOT_ARRIVED"      }    ],    "discrepancies": [      {        "id": "string",        "shipmentNumber": "string",        "externalPoNumber": "string",        "vendorName": "string",        "clientName": "string",        "completedAt": "2019-08-24T14:15:22Z",        "expectedUnits": 0,        "receivedUnits": 0,        "damagedUnits": 0,        "rejectedUnits": 0,        "missingUnits": 0,        "overUnits": 0,        "lines": [          {            "skuId": "string",            "skuCode": "string",            "skuName": "string",            "expectedQuantity": 0,            "receivedQuantity": 0,            "damagedQuantity": 0,            "rejectedQuantity": 0,            "missingUnits": 0,            "overUnits": 0,            "lineStatus": "PENDING",            "isUnexpected": true,            "discrepancyNotes": "string"          }        ],        "linesTruncated": true      }    ],    "thresholds": {      "undatedAgeDays": 0,      "receivingStallDays": 0,      "discrepancyLookbackDays": 0    },    "truncated": {      "overdue": true,      "undated": true,      "discrepancies": true    }  }}

Received but not yet put away

GET
/api/receiving/putaway-queue

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. Stock sitting in non-pickable bins, grouped by the receipt it arrived on, with its age and the open orders finishing the putaway would unblock. Derived rather than task-backed (receiving writes stock straight into its assigned bin), so stock with no matching receipt is reported under unattributed; quarantine bins are excluded.

Authorization

oauth2 receiving:read
AuthorizationBearer <token>

OAuth2 client-credentials grant.

In: header

Scope: receiving:read

Query Parameters

limit?integer

Maximum groups to return.

Range1 <= value <= 100
Default25

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/receiving/putaway-queue"
{  "success": true,  "data": {    "totalUnits": 0,    "totalOrdersBlocked": 0,    "groups": [      {        "inboundShipmentId": "string",        "shipmentNumber": "string",        "externalPoNumber": "string",        "clientName": "string",        "receivedAt": "2019-08-24T14:15:22Z",        "ageHours": 0,        "units": 0,        "skus": [          {            "skuId": "string",            "skuCode": "string",            "skuName": "string",            "units": 0,            "bins": [              "string"            ],            "ordersBlocked": 0,            "unitsShort": 0          }        ],        "ordersBlocked": 0      }    ],    "unattributed": {      "units": 0,      "skus": 0,      "bins": 0    },    "thresholds": {      "receiptLookbackDays": 0    },    "truncated": true  }}

Get an inbound shipment

GET
/api/receiving/shipments/{id}

Authorization

oauth2 receiving:read
AuthorizationBearer <token>

OAuth2 client-credentials grant.

In: header

Scope: receiving:read

Path Parameters

id*string

Inbound 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/receiving/shipments/string"
{  "success": true,  "data": {    "id": "string",    "clientId": "string",    "clientName": "string",    "clientCode": "string",    "warehouseId": "string",    "warehouseName": "string",    "shipmentNumber": "string",    "externalPoNumber": "string",    "status": "PENDING",    "expectedArrival": "2019-08-24T14:15:22Z",    "vendorName": "string",    "trackingNumber": "string",    "expectedPallets": 0,    "expectedCartons": 0,    "receivedPallets": 0,    "receivedCartons": 0,    "notes": "string",    "receivedBy": {      "id": "string",      "firstName": "string",      "lastName": "string",      "email": "string"    },    "createdBy": {      "id": "string",      "firstName": "string",      "lastName": "string",      "email": "string"    },    "lineCount": 0,    "totalExpected": 0,    "totalReceived": 0,    "totalDamaged": 0,    "totalRejected": 0,    "isActive": true,    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z",    "lines": [      {        "id": "string",        "skuId": "string",        "skuCode": "string",        "skuName": "string",        "skuBarcode": "string",        "skuImageUrl": "string",        "expectedQuantity": 0,        "receivedQuantity": 0,        "damagedQuantity": 0,        "rejectedQuantity": 0,        "sellAheadQuantity": 0,        "status": "PENDING",        "binId": "string",        "binLabel": "string",        "quarantineBinId": "string",        "quarantineBinLabel": "string",        "notes": "string",        "discrepancyNotes": "string",        "isUnexpected": true,        "lotTracked": true,        "expiryRequired": true,        "uoms": [          {            "id": "string",            "code": "EACH",            "displayName": "string",            "baseQty": 0          }        ],        "storageRequirementIds": [          "string"        ],        "receipts": [          {            "id": "string",            "binId": "string",            "binLabel": "string",            "quantity": 0,            "uomId": "string",            "lotNumber": "string",            "lotExpiresAt": "2019-08-24T14:15:22Z",            "damagedQuantity": 0,            "quarantineBinId": "string",            "quarantineBinLabel": "string",            "notes": "string",            "performedBy": {              "id": "string",              "firstName": "string",              "lastName": "string",              "email": "string"            },            "createdAt": "2019-08-24T14:15:22Z"          }        ]      }    ]  }}

Update an inbound shipment

PATCH
/api/receiving/shipments/{id}

Allowed while the PO is PENDING or IN_PROGRESS. updateLines[].binId (the putaway location) is warehouse-staff only and is rejected with 403 for API credentials. addLines[].sellAheadQuantity and updateLines[].sellAheadQuantity follow the create rule (never above the line's expectedQuantity, and only when sell ahead is enabled for the client); lowering expectedQuantity below the current sell-ahead clamps it. Every sell-ahead change is recorded in the shipment history. Changing a line's expectedQuantity (through updateLines, or addLines for a SKU already on the PO) recomputes its status in the same write from what has come in, good plus damaged units: PENDING with nothing yet, PARTIAL below expected, COMPLETE at it, OVER above it. Lowering it below what already came in is allowed and makes the line OVER. Those are the open-PO statuses: completing the PO settles each line as COMPLETE, SHORT (less came in, or nothing) or OVER (more came in, or the line wasn't on the PO).

Authorization

oauth2 receiving:write
AuthorizationBearer <token>

OAuth2 client-credentials grant.

In: header

Scope: receiving:write

Path Parameters

id*string

Inbound 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/receiving/shipments/string" \  -H "Content-Type: application/json" \  -d '{}'
{  "success": true,  "data": {    "id": "string",    "clientId": "string",    "clientName": "string",    "clientCode": "string",    "warehouseId": "string",    "warehouseName": "string",    "shipmentNumber": "string",    "externalPoNumber": "string",    "status": "PENDING",    "expectedArrival": "2019-08-24T14:15:22Z",    "vendorName": "string",    "trackingNumber": "string",    "expectedPallets": 0,    "expectedCartons": 0,    "receivedPallets": 0,    "receivedCartons": 0,    "notes": "string",    "receivedBy": {      "id": "string",      "firstName": "string",      "lastName": "string",      "email": "string"    },    "createdBy": {      "id": "string",      "firstName": "string",      "lastName": "string",      "email": "string"    },    "lineCount": 0,    "totalExpected": 0,    "totalReceived": 0,    "totalDamaged": 0,    "totalRejected": 0,    "isActive": true,    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z",    "lines": [      {        "id": "string",        "skuId": "string",        "skuCode": "string",        "skuName": "string",        "skuBarcode": "string",        "skuImageUrl": "string",        "expectedQuantity": 0,        "receivedQuantity": 0,        "damagedQuantity": 0,        "rejectedQuantity": 0,        "sellAheadQuantity": 0,        "status": "PENDING",        "binId": "string",        "binLabel": "string",        "quarantineBinId": "string",        "quarantineBinLabel": "string",        "notes": "string",        "discrepancyNotes": "string",        "isUnexpected": true,        "lotTracked": true,        "expiryRequired": true,        "uoms": [          {            "id": "string",            "code": "EACH",            "displayName": "string",            "baseQty": 0          }        ],        "storageRequirementIds": [          "string"        ],        "receipts": [          {            "id": "string",            "binId": "string",            "binLabel": "string",            "quantity": 0,            "uomId": "string",            "lotNumber": "string",            "lotExpiresAt": "2019-08-24T14:15:22Z",            "damagedQuantity": 0,            "quarantineBinId": "string",            "quarantineBinLabel": "string",            "notes": "string",            "performedBy": {              "id": "string",              "firstName": "string",              "lastName": "string",              "email": "string"            },            "createdAt": "2019-08-24T14:15:22Z"          }        ]      }    ]  }}

Cancel an inbound shipment

POST
/api/receiving/shipments/{id}/cancel

Allowed while PENDING, or IN_PROGRESS with nothing received yet.

Authorization

oauth2 receiving:write
AuthorizationBearer <token>

OAuth2 client-credentials grant.

In: header

Scope: receiving:write

Path Parameters

id*string

Inbound 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/receiving/shipments/string/cancel"
{  "success": true,  "data": {    "id": "string",    "clientId": "string",    "clientName": "string",    "clientCode": "string",    "warehouseId": "string",    "warehouseName": "string",    "shipmentNumber": "string",    "externalPoNumber": "string",    "status": "PENDING",    "expectedArrival": "2019-08-24T14:15:22Z",    "vendorName": "string",    "trackingNumber": "string",    "expectedPallets": 0,    "expectedCartons": 0,    "receivedPallets": 0,    "receivedCartons": 0,    "notes": "string",    "receivedBy": {      "id": "string",      "firstName": "string",      "lastName": "string",      "email": "string"    },    "createdBy": {      "id": "string",      "firstName": "string",      "lastName": "string",      "email": "string"    },    "lineCount": 0,    "totalExpected": 0,    "totalReceived": 0,    "totalDamaged": 0,    "totalRejected": 0,    "isActive": true,    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z",    "lines": [      {        "id": "string",        "skuId": "string",        "skuCode": "string",        "skuName": "string",        "skuBarcode": "string",        "skuImageUrl": "string",        "expectedQuantity": 0,        "receivedQuantity": 0,        "damagedQuantity": 0,        "rejectedQuantity": 0,        "sellAheadQuantity": 0,        "status": "PENDING",        "binId": "string",        "binLabel": "string",        "quarantineBinId": "string",        "quarantineBinLabel": "string",        "notes": "string",        "discrepancyNotes": "string",        "isUnexpected": true,        "lotTracked": true,        "expiryRequired": true,        "uoms": [          {            "id": "string",            "code": "EACH",            "displayName": "string",            "baseQty": 0          }        ],        "storageRequirementIds": [          "string"        ],        "receipts": [          {            "id": "string",            "binId": "string",            "binLabel": "string",            "quantity": 0,            "uomId": "string",            "lotNumber": "string",            "lotExpiresAt": "2019-08-24T14:15:22Z",            "damagedQuantity": 0,            "quarantineBinId": "string",            "quarantineBinLabel": "string",            "notes": "string",            "performedBy": {              "id": "string",              "firstName": "string",              "lastName": "string",              "email": "string"            },            "createdAt": "2019-08-24T14:15:22Z"          }        ]      }    ]  }}

Get an inbound shipment's history

GET
/api/receiving/shipments/{id}/history

Authorization

oauth2 receiving:read
AuthorizationBearer <token>

OAuth2 client-credentials grant.

In: header

Scope: receiving:read

Path Parameters

id*string

Inbound shipment id

Query Parameters

page?integer
Range0 < value
Default1
limit?integer
Range0 < value <= 500
Default20

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/receiving/shipments/string/history"
{  "success": true,  "data": [    {      "id": "string",      "action": "CREATED",      "field": "string",      "previousValue": null,      "newValue": null,      "notes": "string",      "performedBy": {        "firstName": "string",        "lastName": "string",        "email": "string"      },      "createdAt": "2019-08-24T14:15:22Z"    }  ],  "pagination": {    "page": 0,    "limit": 0,    "total": 0,    "totalPages": 0  }}

Shipping

Previous Page

Returns

Next Page