Supplier Shipments

Supplier shipments are inbound purchase-order shipments expected at the 3PL's warehouse. The integration polls for them, acknowledges receipt, and reports per-SKU received quantities including lot and expiry data where applicable.

List supplier shipments 🔗

Text

1
GET /v1/supplier-shipments.json

Query parameters

Name	Type	Description
`status`	string	`pending` (default), `open`, `done`
`page`	integer	1-indexed page number (100 records per page)
`planned_date_min`	date	Lower bound on `planned_date`
`planned_date_max`	date	Upper bound on `planned_date`
`updated_at_min`	datetime	Lower bound on last modification time
`updated_at_max`	datetime	Upper bound on last modification time

Status meanings

pending — expected at the warehouse, not yet acknowledged by the 3PL
open — acknowledged, still being received
done — fully received

Response

JSON

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
{
  "data": [
    {
      "id": 200456,
      "number": "SS-200456",
      "company_code": "ACME",
      "warehouse": { "id": 3, "code": "LAX", "name": "Los Angeles" },
      "reference": "PO-EXT-9988",
      "supplier": { "name": "Widget Co", "code": "WIDCO" },
      "planned_date": "2026-06-25",
      "carrier_code": "ups",
      "service_code": "ground",
      "incoterm": "FOB",
      "transportation_mode": "truck",
      "packages": [],
      "purchase_orders": [
        {
          "id": 780,
          "number": "PO-780",
          "reference": "PO-EXT-9988",
          "purchase_date": "2026-06-01"
        }
      ],
      "lines": [
        {
          "id": 6001,
          "product": { "code": "SKU-100", "name": "Widget" },
          "quantity": 100,
          "unit": "u",
          "order_line": { "id": 900, "unit_price": 12.50 },
          "order": { "id": 780, "number": "PO-780", "currency": "USD" }
        }
      ],
      "tracking_number": null
    }
  ],
  "has_more": false
}

Count supplier shipments 🔗

Text

1
GET /v1/supplier-shipments/count.json

Same filters as the list endpoint. Returns {"count": <n>}.

Acknowledge supplier shipments 🔗

Text

1
PUT /v1/supplier-shipments/acknowledge.json

Signals to Fulfil that the 3PL has received the notification and expects the shipment. The shipment must be in the inbound state (or draft where that feature flag is enabled) and not already acknowledged.

Request body

JSON

1
2
3
{
  "shipments": [{ "id": 200456 }]
}

Response

JSON

1
2
3
4
5
{
  "shipments": [
    { "id": 200456, "acknowledged_at": "2026-06-17T18:33:00+00:00", "errors": null }
  ]
}

Returns 200 if every item succeeded, 207 if some failed.

Receive supplier shipments 🔗

Text

1
PUT /v1/supplier-shipments/receive.json

Mark supplier shipments as received and post per-SKU received quantities into Fulfil. Lot tracking, expiry dates, and EPC codes are supported when the warehouse has lot inventory enabled.

Request body

JSON

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  "shipments": [
    {
      "id": 200456,
      "tpl_reference": "WH-RCPT-7788",
      "receiving_strategy": "finalize_and_start_new",
      "lines": [
        {
          "sku": "SKU-100",
          "received_quantity": 98,
          "damaged_quantity": 2,
          "lot_number": "LOT-A",
          "lot_expiry_date": "2027-01-15"
        }
      ]
    }
  ]
}

Line fields

Field	Type	Notes
`sku`	string	Required
`received_quantity`	number	At least one of `received_quantity` or `damaged_quantity` is required. Legacy `quantity` is accepted as an alias for `received_quantity`.
`damaged_quantity`	number	See above
`lot_number`	string	Required for lot-tracked SKUs
`lot_expiry_date`	date	Requires `lot_number`
`epc`	string	Optional EPC code

receiving_strategy values

finalize_and_start_new (default) — close the original shipment; open a new one for any remaining quantity
split_and_keep_open — split off the received portion; keep the original open

Response

JSON

1
2
3
4
5
{
  "shipments": [
    { "id": 200456, "errors": null }
  ]
}

Returns 200 / 207 with per-item errors.

Report a failure 🔗

Text

1
2
PATCH /v1/supplier-shipments/failed.json
POST  /v1/supplier-shipments/failed.json

Tell Fulfil that the 3PL could not process specific supplier shipments.

Request body

JSON

1
2
3
4
5
{
  "shipments": [
    { "id": 200456, "error": "Rejected by receiving dock — damaged pallet" }
  ]
}

Response

JSON

1
2
3
4
5
{
  "shipments": [
    { "id": 200456, "tpl_status": "sending_error", "errors": null }
  ]
}

Returns 200 / 207 with per-item errors.