Returns the shipments that match the given filters, each with its lines.

POST /inventory/shipments/search

Group: Inventory › Shipments · Operation ID: searchShipments

This is the only endpoint that returns the lines, and the only one that filters by customer, reference number or tracking number. Every criterion is exact or a range, and criteria combine with AND. Send an empty filters object to return every shipment.

Open in the interactive reference

Parameters

Name In Type Required Description
Api-Version header "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: searchShipmentsInput.

Field Type Required Description
filters object yes The filters to apply. A shipment must match every filter you send. Send an empty object to return all shipments.
filters.documentNumber string no Limits results to the shipment with this document number. The match is exact.
filters.documentStatus string no Limits results to shipments with this status. The match is exact. Possible values: 'DRAFT', 'PACKED', 'PARTIALLY_SHIPPED', 'SHIPPED', 'COMMITTED', 'DELIVERED', 'COMPLETED', 'CANCELLED', 'INVOICED', 'PARTIALLY_INVOICED', 'RETURNED', 'PARTIALLY_RETURNED'.
filters.entityId string no Limits results to shipments for the legal entity with this identifier.
filters.businessPartnerId string no Limits results to shipments for the customer with this identifier. Despite the name, this is a customer id.
filters.locationId string no Limits results to shipments with a line for the warehouse with this identifier.
filters.itemId string no Limits results to shipments with a line for the item with this identifier.
filters.referenceNumber string no Limits results to the shipment with this customer reference. The match is exact.
filters.trackingNumber string no Limits results to the shipment with this carrier tracking number. The match is exact.
filters.fromDate string (date) no Limits results to shipments dated on or after this date. Format YYYY-MM-DD.
filters.toDate string (date) no Limits results to shipments dated on or before this date. Format YYYY-MM-DD.
filters.modifiedSince string (date-time) no Limits results to shipments changed on or after this time. Format YYYY-MM-DDTHH:mm:ss.sssZ.
page object no The pagination controls. Omit for the first page.
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.

Example:

{
  "filters": {
    "documentStatus": "SHIPPED"
  },
  "page": {
    "cursor": "<cursor>",
    "size": 0
  }
}

Response

200 Success

Under data (searchShipmentsOutput):

Field Type Required Description
items array of object yes The shipments on this page, each with its lines. An empty array when nothing matches.
items[].id string yes The unique identifier for the shipment.
items[].documentNumber string no The shipment's document number, for example 'SD-8841'. Absent while none has been assigned.
items[].documentStatus string yes The status of the shipment. Possible values: 'DRAFT', 'PACKED', 'PARTIALLY_SHIPPED', 'SHIPPED', 'COMMITTED', 'DELIVERED', 'COMPLETED', 'CANCELLED', 'INVOICED', 'PARTIALLY_INVOICED', 'RETURNED', 'PARTIALLY_RETURNED'.
items[].documentDate string (date) yes The date the shipment is dated. Format YYYY-MM-DD.
items[].deliveryDate string (date) no The planned or actual delivery date. Format YYYY-MM-DD.
items[].entityId string yes The unique identifier for the legal entity the shipment belongs to. See id on GET base/entities.
items[].entityName string no The display name of that legal entity.
items[].businessPartnerId string yes The unique identifier for the customer the goods go to. Despite the name, this is a customer id. See id on GET accounting/customers/:id.
items[].businessPartnerName string no The display name of that customer.
items[].shipmentCarrierId string no The unique identifier for the carrier taking the goods. See id on GET inventory/shipment-carriers/:id.
items[].shipmentCarrierName string no The name of that carrier.
items[].trackingNumber string no The carrier's tracking number for the goods.
items[].referenceNumber string no The customer's own reference for the shipment.
items[].returnStatus string no How much of the shipment has come back on sales returns. Possible values: 'OPEN', 'PARTIALLY_RETURNED', 'FULLY_RETURNED'. The return process maintains it.
items[].currency string no The currency of every amount on the shipment. Format ISO 4217, for example 'EUR'.
items[].totalAmount string (decimal) no The total value of the shipment, in the shipment's currency.
items[].notes string no Free text on the shipment.
items[].createdDate string (date-time) no The date and time the shipment was created, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ.
items[].lastModifiedDate string (date-time) no The date and time the shipment record last changed, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ.
items[].lines array of object yes The lines of the shipment. A shipment always has at least one.
items[].lines[].id string yes The unique identifier for the shipment line.
items[].lines[].itemId string yes The unique identifier for the item going out. See id on GET inventory/items/:id.
items[].lines[].itemCode string no The short code of that item.
items[].lines[].itemName string no The display name of that item.
items[].lines[].locationId string no The unique identifier for the warehouse the goods leave from. Every line of a shipment must use the same warehouse. See id on GET inventory/warehouses/:id.
items[].lines[].locationCode string no The short code of that warehouse.
items[].lines[].locationName string no The display name of that warehouse.
items[].lines[].unitId string yes The unique identifier for the unit the quantity is counted in. See id on GET inventory/unit-of-measures/:id.
items[].lines[].unitCode string no The short code of that unit.
items[].lines[].quantity string (decimal) yes The quantity going out, in the line's unit.
items[].lines[].inventoryQuantity string (decimal) no The same quantity in the item's stocking unit.
items[].lines[].pickedQuantity string (decimal) no How much of the line has been picked. This API does not set it.
items[].lines[].packedQuantity string (decimal) no How much of the line has been packed. This API does not set it.
items[].lines[].returnedQuantity string (decimal) no How much of the line has come back on a sales return.
items[].lines[].openReturnQuantity string (decimal) no How much of the line may still be returned.
items[].lines[].unitPrice string (decimal) no The value of one unit, in the shipment's currency.
items[].lines[].status string no Where the line sits in the warehouse process. This is free text with no fixed set of values.
items[].lines[].sourceDocumentLineId string no The sales order line this line ships against. Each order publishes its lines as items[].id on GET accounting/sales-orders/:id.
items[].lines[].sourceDocumentLineType string, one of "IMInventorySalesOrderLine", "IMInventorySalesDeliveryLine", "IMSalesOrderLine", "IMInventoryPurchaseReturnLine", "IMInventorySalesReturnLine", "IMWarehouseTransferLine", "IMInventoryDecreaseLine", "IMInventoryIncreaseLine", "IMInventoryRevaluationLine", "IMInventoryTransferLine", "IMInventoryAdjustmentLine", "IMInventoryCountLine", "IMInventoryPutAwayTask", "IMInventoryPurchaseReturnReversal", "PurchaseOrderLine", "IMLandedCostAllocationLine", "SalesOrderProductItem", "IMWarehouseTransferOrderLine", "VendorBillItemBase", "InvPurchaseDeliveryLine" no The kind of document line the source line is.
items[].lines[].notes string no Free text on the line.
items[].lines[].batches array of object no The batches going out on this line, for a batch-tracked item. Absent when the item is not batch-tracked.
items[].lines[].batches[].batchNumberId string no The unique identifier for the batch record.
items[].lines[].batches[].batchNumber string yes The batch number as printed.
items[].lines[].batches[].expirationDate string (date) no The expiration date of the batch. Format YYYY-MM-DD.
items[].lines[].batches[].quantity string (decimal) yes The quantity of this batch going out, in the line's unit.
items[].lines[].batches[].inventoryQuantity string (decimal) no The same quantity in the item's stocking unit.
items[].lines[].batches[].returnedQuantity string (decimal) no How much of this batch has come back on a sales return.
items[].lines[].batches[].unitCost string (decimal) no The cost of one unit of this batch at shipment, in the shipment's currency.
items[].lines[].serials array of object no The serialized units going out, one entry per unit. Absent when the item is not serialized.
items[].lines[].serials[].serialNumberId string no The unique identifier for the serial record.
items[].lines[].serials[].serialNumber string yes The serial number stamped on the unit.
items[].lines[].serials[].returnedQuantity string (decimal) no How much of this unit has come back on a sales return.
items[].lines[].serials[].unitCost string (decimal) no The cost of this unit at shipment, in the shipment's currency.
items[].lines[].binLocations array of object no The bins the goods come out of, in a bin-tracked warehouse. Each entry that names a batchNumber or serialNumber belongs to that batch or unit, and one that names neither belongs to the line.
items[].lines[].binLocations[].binLocationId string yes The unique identifier for the bin the goods come out of. See id on GET inventory/bins/:id.
items[].lines[].binLocations[].binLocationCode string no The short code of that bin.
items[].lines[].binLocations[].quantity string (decimal) yes The quantity taken from this bin, in the line's unit.
items[].lines[].binLocations[].inventoryQuantity string (decimal) no The same quantity in the item's stocking unit.
items[].lines[].binLocations[].batchNumber string no The batch this bin entry belongs to, when it belongs to one of the line's batches.
items[].lines[].binLocations[].serialNumber string no The serialized unit this bin entry belongs to, when it belongs to one of the line's units.
pagination object yes The pagination cursor for this page.
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.

Statuses