# List Shipments

Endpoint: GET /shipments
Version: V5
Security: basicAuth

## Query parameters:

  - `merchant_invoice_id` (string)
    Filter shipments by specific merchant invoice ID.
    Example: "inv_1234567890abcdef"

  - `fulfillment_method` (string)
    Filter shipments by fulfillment method.
    Enum: "shipping_provider", "self_delivery", "customer_pickup", "services_only"

  - `verification_status` (string)
    Filter shipments by verification status.
    Enum: "verified", "pending"

  - `shipment_courier` (string)
    Filter shipments by shipping courier.
    Example: "ups"

  - `limit` (integer)
    Number of results to return per page (1-100).
    Example: 25

  - `starting_after` (string)
    Pagination cursor for fetching results after a specific shipment ID.
    Example: "ship_1234567890abcdef"

  - `ending_before` (string)
    Pagination cursor for fetching results before a specific shipment ID.
    Example: "ship_9876543210fedcba"

  - `search` (string)
    Search term to filter shipments across multiple fields.
    Example: "1Z123E45678901234"

  - `searchBy` (string)
    Specific field to search within.
    Enum: "tracking_number", "courier", "id", "merchant_invoice_id"

  - `sort` (string)
    Sort records by the specified fields.

The sort order for each sort field is ascending unless it is prefixed with a minus,
in which case it is descending.

Multiple sort fields supported by allowing comma-separated sort fields. Sort fields will be applied in the order specified.

Sorting is allowed by the following fields: id, created_at.

Example: sort=id,-created_at

## Response 200 fields (application/json):

  - `limit` (integer)
    Number of results returned per page.
    Example: 10

  - `page` (integer)
    Current page number.
    Example: 1

  - `count` (integer)
    Total number of shipments matching the query.
    Example: 25

  - `results` (array)

  - `results.id` (string)
    Unique identifier of the Shipment.
    Example: "ship_1234567890abcdef"

  - `results.merchant_invoice_id` (string)
    ID of the associated merchant invoice.
    Example: "inv_1234567890abcdef"

  - `results.fulfillment_method` (string)
    Method of fulfillment for the shipment.
    Enum: "shipping_provider", "self_delivery", "customer_pickup", "services_only"

  - `results.shipment_tracking_number` (string)
    Tracking number provided by the shipping courier.
    Example: "1Z123E45678901234"

  - `results.shipment_courier` (string)
    Shipping courier or provider name. While any value can be accepted, instant verification is supported for specific couriers.

See the [Shipments API documentation](#tag/Shipments) for the complete list of supported couriers.
    Example: "ups"

  - `results.verification_status` (string)
    Manual or automatic verification status of the shipment.
    Enum: "verified", "pending"

  - `results.created_at` (string)
    Date time when the shipment was created.
    Example: "2024-01-15T10:30:00Z"

  - `results.updated_at` (string)
    Date time when the shipment was last updated.
    Example: "2024-01-15T14:45:00Z"

  - `results.tracking_status` (string,null)
    Current tracking status of the shipment from the courier.
    Example: "delivered"

  - `results.tracking_substatus` (string,null)
    Detailed tracking substatus providing additional context about the shipment's current state.
    Example: "delivered_001"

  - `results.expected_delivery` (string,null)
    Expected delivery date and time provided by the shipping courier.
    Example: "2024-01-20T18:00:00Z"

## Response 401 fields (application/json):

  - `error` (object)

  - `error.message` (string)
    A short string, describing error details
    Example: "Invalid merchant credentials"

  - `error.type` (string)
    A short string, describing error type
    Enum: "authentication_error"

## Response 429 fields (application/json):

  - `error` (object)

  - `error.message` (string)
    A short string, describing error details
    Example: "Too many requests"

  - `error.type` (string)
    A short string, describing error type
    Enum: "rate_limit_error"