Skip to main content

GET v3/shipments

GET 
/v3/shipments

List shipments from the last 90 days, with filters and pagination.

Returns a collection of up to 100 shipment resources, non older than 90 days, that match the provided filerting criteria and allows for iterating over pages of more shipment resources if there are more available. The endpoint supports pagination and filtering as described in the chapters below.

Pagination​

The endpoint supports pagination to split the large collection of resources into smaller, more manageable chunks or pages. This helps to reduce the response size and to improve performance. The endpoint supports only cursor-based technique for pagination.

Filters​

The GET v3/shipments endpoint supports filtering on the following attributes: shippedOn, orderType, status, orderId, externalOrderNumber. Each of these are explained below. Filters can be used in combination with eachother and with pagination as to allow full access to the desired subset of shipments.

Filtering on shippedOn​

The results returned by this service can be filtered based on the shipping date of the shipments. To do so make use of the filter[shippedOn] parameter in the following manner:

  • GET {host}/v3/shipments?filter[shippedOn][lt]={date} will return shipments that have shipped before the provided date. Shipments that shipped on that date are not included in the results.
  • GET {host}/v3/shipments?filter[shippedOn][gt]={date} will return shipments that have shipped after the provided date. Shipments that shipped on that date are not included in the results.
  • GET {host}/v3/shipments?filter[shippedOn][gt]={date_1}&filter[shippedOn][lt]={date_2} will return shipments that have shipped between dates {date_1} and {date_1}. Shipments that shipped on either date are not included in the results.

Filtering on status​

The results returned by this service can be filtered based on the status of the shipments. To do so make use of the filter[status][in] parameter in the following manner:

  • GET {host}/v3/shipments?filter[status][in]=READY_TO_SHIP,SHIPPED will return shipments that have been picked and packed and are awaiting pickup by the carrier or have been picked up by the carrier.
  • GET {host}/v3/shipments?filter[status][in]=READY_TO_PICK will return shipments that are waiting for physical processing in the warehouse.

Filtering on orderType​

The endpoint allows filtering on one or more orderType values of the order(s) that form the bases of the shipments. An orderType is a required paramter on the order and determines various asects of how the order should be processed. To filter on orderType use the filter[orderType][in] query parameter as follows:

  • GET {host}/v3/shipments?filter[orderType][in]=1 will return all shipments that belong to an order with the orderType set to 1.
  • GET {host}/v3/shipments?filter[orderType][in]=5,6,7 will return all shipments that belong to an order with the orderType set to 5, 6 or 7.

Filtering on orderId, externalOrderNumber and reference​

The endpoint allows filtering on both orderId, externalOrderNumber and reference of the order(s) that the shipments are created for. To filter using one or more of these filters follow the examples below:

  • GET {host}/v3/shipments?filter[orderId][in]=123 will return all shipments are created for an order with id equal to 123. To filter on externalOrderNumber use the filter[externalOrderNumber][in] query parameter as follows:
  • GET {host}/v3/shipments?filter[externalOrderNumber][in]=abc,123,1a2b will return all shipments that are created for orders with external order numbers set to corresponding values.
  • GET {host}/v3/shipments?filter[orderId][in]=123&filter[externalOrderNumber][in]=abc will return all shipments that are created for orders with orderId = 123 and externalOrderNumber=abc.
  • GET {host}/v3/shipments?filter[reference][in]=cust1,cust2,cust3 will return all shipments that are created for orders with reference set to corresponding values.

The endpoint also supports -to some degree- the inclusion of information of related resources. To get the details of related entities the include parameter must be added to the URI in the following way:

  • GET {host}/v3/shipments?include=shipmentItems will return the shipment with all shipmentItems details.

Limitations of GET v3/shipments​

  • When using this endpoint, expect the following limits on the result set:
    • Shipments older than 90 days are not returned using this method.
    • At most 100 shipments will be returned regardless of the page[size] settings provided in the request.
    • Ordering is based on the id of the shipment in ascending order.
    • Some shipment statusses are suppressed from the results when retreiving shipments in bulk using the GET v3/shipments.
  • Users are rate-limited to 1000 requests per hour on this service.

Request​

Responses​

A successful response consists of zero or more shipment resources being returned as part of the data element in the response body that match the filterng and pagination query parameters provided in the request. Also a set of pagination links will be returned to assist with further invokations of the endpoint.