Search sales order shipments

Operation ID: searchSalesOrderShipments

Group: Accounting › Sales Order Shipments

Open in the interactive reference

POST /accounting/sales-order-shipments/search

Read-only: A read that takes its filters in the body. Changes nothing, and ignores Idempotency-Key.

Searches sales order shipments. Unlike GET accounting/sales-order-shipments, this endpoint matches part of the carrier, tracking id, shipment number, incoterm, or shipping contact email. It also filters by several statuses at once, by the customer's requested delivery date, and by the shipped sales order product item.

Parameters

Name In Type Required Description
Api-Version header string · v1 yes The API version this request targets, named by its public identifier. Required on every request; omitting it, or naming a version this company does not have, is answered with 400. This document describes version v1.

Request body

Required, application/json: searchSalesOrderShipmentsInput.

Field Type Required Description
filters object no The filters to apply. A shipment must match every filter you send. Omit to return all shipments. Example: {"carrier":"dhl","status":["pendingShipment","shipped"]}.
filters.salesOrderId string no Limits results to shipments that fulfill this sales order. See id on GET accounting/sales-orders/:id.
filters.inventoryShipmentId number no Limits results to the shipment mirroring this inventory shipment, given as its numeric inventory shipment id. At most one shipment matches.
filters.warehouseId string no Limits results to shipments dispatched from this warehouse location. See id on GET inventory/warehouses/:id.
filters.status array<any> no Limits results to shipments in any of these states. Omit or pass an empty array to match every state.
filters.salesOrderProductItemId string no Limits results to shipments for this sales order product item. See items[].id on GET accounting/sales-orders/:id.
filters.shipmentNumber string no Limits results to shipments whose shipment number contains this text. The match is case-insensitive.
filters.trackingId string no Limits results to shipments whose tracking number or URL contains this text. The match is case-insensitive.
filters.carrier string no Limits results to shipments whose carrier name contains this text. The match is case-insensitive.
filters.incoterm string no Limits results to shipments whose incoterm contains this text. The match is case-insensitive.
filters.shipToContactEmail string no Limits results to shipments whose shipping contact email contains this text. The match is case-insensitive.
filters.shipDate object no Limits results by dispatch date. Both bounds are inclusive. Omit one to leave that side open.
filters.shipDate.start date no The earliest dispatch date to include, inclusive. Format YYYY-MM-DD.
filters.shipDate.end date no The latest dispatch date to include, inclusive. Format YYYY-MM-DD.
filters.deliveryDate object no Limits results by delivery date. Both bounds are inclusive. Omit one to leave that side open.
filters.deliveryDate.start date no The earliest delivery date to include, inclusive. Format YYYY-MM-DD.
filters.deliveryDate.end date no The latest delivery date to include, inclusive. Format YYYY-MM-DD.
filters.customerRequestDate object no Limits results by the date the customer requested delivery. Both bounds are inclusive. Omit one to leave that side open.
filters.customerRequestDate.start date no The earliest requested delivery date to include, inclusive. Format YYYY-MM-DD.
filters.customerRequestDate.end date no The latest requested delivery date to include, inclusive. Format YYYY-MM-DD.
filters.lastModifiedDate object no Limits results by last change. Both bounds are inclusive. Format YYYY-MM-DDTHH:mm:ss.sssZ in UTC. Omit one to leave that side open.
filters.lastModifiedDate.start date-time no The earliest change time to include, inclusive. Format YYYY-MM-DDTHH:mm:ss.sssZ in UTC.
filters.lastModifiedDate.end date-time no The latest change time to include, inclusive. Format YYYY-MM-DDTHH:mm:ss.sssZ in UTC.
page object no The pagination controls. Omit for the first page. Example: {"size":50}.
page.cursor string no The cursor from the previous response's pagination.nextCursor. Omit for the first page.
page.size number no The number of shipments per page. Defaults to 50. A value above 200 is treated as 200, not rejected. 
{
  "filters": {
    "carrier": "dhl",
    "status": [
      "pendingShipment",
      "shipped"
    ]
  },
  "page": {
    "size": 50
  }
}

Response

200 Success

Under data (searchSalesOrderShipmentsOutput):

Field Type Required Description
items array<object> yes The shipments on this page, ordered by ship date with the most recent first. An empty array when nothing matches. Example: [{"id":"3b7d5e9c-1a24-4f80-9c6d-2e8f70b13a45","salesOrderId":"9c2a6a10-7d34-4c8e-9b21-5a0f3e6d81b7","inventoryShipmentId":4242,"shipmentNumber":"SHP-1042","status":"shipped","carrier":"DHL","shipDate":"2026-08-19","lastModifiedDate":"2026-08-20T10:15:00.000Z","items":[]}].
items[].id string yes The unique identifier for the sales order shipment.
items[].salesOrderId string yes The sales order this shipment fulfills. See id on GET accounting/sales-orders/:id.
items[].inventoryShipmentId number no The numeric identifier of the shipment document in inventory, which owns the shipment. Absent only on legacy rows written before the mirroring existed.
items[].shipmentNumber string no The shipment document number, assigned by inventory. Absent until inventory has issued one.
items[].status string no The lifecycle status of the shipment. Possible values: 'pendingShipment', 'shipped', 'cancelled'. 'pendingShipment' is drafted in inventory but not yet dispatched, 'shipped' is dispatched, and 'cancelled' means the inventory shipment was deleted and this mirror was soft-canceled.
items[].trackingId string no The carrier tracking number or tracking URL, when one has been recorded.
items[].carrier string no The name of the carrier handling the shipment.
items[].incoterm string no The incoterm governing shipping responsibility for this shipment. For example 'DAP' or 'EXW'.
items[].warehouseId string no The warehouse location the shipment is dispatched from. See id on GET inventory/warehouses/:id.
items[].shipToContactEmail string no The email of the contact who receives this shipment.
items[].customerRequestDate date no The date the customer asked for delivery. Format YYYY-MM-DD.
items[].shipDate date no The date the shipment was dispatched. Format YYYY-MM-DD. Absent while the shipment is still pending.
items[].deliveryDate date no The date the shipment was, or is expected to be, delivered. Format YYYY-MM-DD.
items[].lastModifiedDate date-time yes The date and time the shipment last changed, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ.
items[].items array<object> yes The shipped lines, oldest first. An empty array when the shipment has no lines.
items[].items[].id string yes The unique identifier for the shipment line. PATCH matches updateItems and deleteItems on it.
items[].items[].salesOrderProductItemId string yes The sales order product item this shipment line is for. See items[].id on GET accounting/sales-orders/:id.
items[].items[].shippedQty decimal yes The quantity shipped on this line, as a count of units.
items[].items[].orderedQty decimal yes The total quantity ordered for the sales order product item, as a count of units.
items[].items[].unshippedQty decimal yes The quantity still outstanding on this line, as a count of units: orderedQty minus shippedQty.
pagination object yes The pagination cursor for this page. Example: {"hasMore":false}.
pagination.nextCursor string no The cursor for the next page. Pass it as page.cursor. Absent on the last page.
pagination.hasMore boolean yes True when more shipments remain beyond this page. 
{
  "data": {
    "items": [
      {
        "id": "3b7d5e9c-1a24-4f80-9c6d-2e8f70b13a45",
        "salesOrderId": "9c2a6a10-7d34-4c8e-9b21-5a0f3e6d81b7",
        "inventoryShipmentId": 4242,
        "shipmentNumber": "SHP-1042",
        "status": "shipped",
        "carrier": "DHL",
        "shipDate": "2026-08-19",
        "lastModifiedDate": "2026-08-20T10:15:00.000Z",
        "items": []
      }
    ],
    "pagination": {
      "hasMore": false
    }
  },
  "diagnostics": [
    {
      "code": "<code>",
      "message": "<message>",
      "severity": "error",
      "path": [
        "<path>"
      ],
      "details": "<details>"
    }
  ]
}

Statuses