Passa al contenuto principale

Get shipments list

GET 
/shipments

Returns the list of shipments filtered by the specified parameters. If no filter is specified, the full list of shipments is returned. Pagination is supported using the limit and page parameters. The returned has_more field determines if there are more shipments to retrieve.

The list of shipments is ordered by creation date, from the oldest to the most recent. The created_after filter can be used to retrieve only the shipments created after the specified date and time.

Tip

The checkpoints_updated_after filter can be used to retrieve only the shipments with updates in the checkpoints history published after the specified date and time. You can use this parameter to sync your systems by retrieving only shipments that had tracking changes since the previous request.

Request​

Query Parameters

    limit integer

    Possible values: >= 1 and <= 100

    Default value: 30

    Maximum number of shipments to return per page. Used for pagination.

    page integer

    Possible values: >= 1

    Default value: 1

    Page number of the list of shipments. Used for pagination.

    tracking_code string

    Filter shipments with the specified tracking code. More than one result can be returned if multiple shipments with the same tracking code exist in the account.

    courier string

    Filter shipments handled by the specified courier. The list of couriers is available in the Supported couriers page.

    status StatusFilter

    Possible values: [in_progress, completed, unknown, info_received, in_transit, out_for_delivery, delivered, attempt_fail, available_for_pickup, exception, inactive, returned_to_sender]

    Filter shipments with the specified status. If not specified, shipments with any status will be returned.

    • completed is a special status that corresponds to delivered and returned_to_sender shipments.
    • in_progress is a special status that corresponds to any status except the ones included in completed.
    checkpoints_updated_after date-time

    Filter shipments with checkpoints history updated after the specified date and time. The datetime must be in ISO 8601 format.

    created_after date-time

    Filter shipments created after the specified date and time. The datetime must be in ISO 8601 format.

    archived boolean

    Filter shipments that are archived or not archived. For example, pass false to filter non-archived shipments. If not specified, both archived and non-archived shipments will be returned.

Responses​

List of shipments filtered with the specified parameters.

Schema

    has_more boolean

    data

    object[]

  • Array [

    • id string

    Unique identifier of the shipment.

    tracking_code string

    Tracking code of the shipment.

    courier string

    Courier slug. The possible values are listed in the Supported couriers page.

    type ShipmentType (string)

    Possible values: [send, receive]

    Shipment type. Determines if the shipment is outgoing or incoming.

    created_at date-time

    Timestamp of the creation of the shipment in the system. ISO 8601 format.

    order_number stringnullable

    Optional order number associated with the shipment.

    description stringnullable

    Additional notes that are visible only to the account owner.

    archived_at date-timenullable

    Timestamp of the archiving of the shipment. ISO 8601 format.

    archive_reason ArchiveReason (string)nullable

    Possible values: [delivered, expired, manual, null]

    Determines the reason of the archiving of the shipment.

    shipped_at date-timenullable

    Timestamp of the first in_transit checkpoint. ISO 8601 format without the UTC offset (local date time). When the time is not specified, it is set to midnight.

    transit_days integer

    Number of days in transit. The first day until midnight is considered as day 0.

    delivered_at date-timenullable

    Timestamp of the delivery of the shipment. ISO 8601 format without the UTC offset (local date time). When the time is not specified, it is set to midnight.

    last_check_at date-timenullable

    Timestamp of the last time that the system checked for new checkpoints. ISO 8601 format.

    checkpoints_updated_at date-timenullable

    Timestamp of the last time that the checkpoints history was updated. ISO 8601 format.

    checkpoints

    object[]

  • Array [

    • id string

    Unique identifier of the checkpoint.

    created_at date-time

    Timestamp of the creation of the checkpoint in the system. ISO 8601 format.

    message string

    Message published by the courier.

    location stringnullable

    Location of the checkpoint, if provided by the courier.

    date_time date-timenullable

    Date and time of the checkpoint, if provided by the courier. ISO 8601 format without the UTC offset (local date time). When the time is not specified, it is set to midnight.

    notes stringnullable

    Additional notes provided by the courier.

    status CheckpointStatus (string)

    Possible values: [unknown, info_received, in_transit, out_for_delivery, delivered, attempt_fail, available_for_pickup, exception, delayed, returned_to_sender]

    Status of the checkpoint.

    substatus Substatus (string)nullable

    Possible values: [exception_generic, exception_incorrect_address, exception_storage, exception_refused, exception_damaged, exception_lost, exception_returning_to_sender, null]

    Substatus of the checkpoint, available only when the status is exception.

  • ]

    • status ShipmentStatus (string)

    Possible values: [unknown, info_received, in_transit, out_for_delivery, delivered, attempt_fail, available_for_pickup, exception, inactive, returned_to_sender]

    Status of the shipment computed from the checkpoints history. It can be different from the status of the last checkpoint.

    substatus Substatus (string)nullable

    Possible values: [exception_generic, exception_incorrect_address, exception_storage, exception_refused, exception_damaged, exception_lost, exception_returning_to_sender, null]

    Substatus of the shipment, available only when the status is exception.

    is_delayed boolean

    true if a delay in the shipment was detected in the tracking history.

    estimated_delivery_date datenullable

    Estimated delivery date indicated by the courier. ISO 8601 format with only the date.

    estimated_delivery_time stringnullable

    Estimated delivery time range indicated by the courier.

    recipient_name stringnullable

    Name of the recipient of the shipment.

    recipient_email emailnullable

    Email of the recipient.

    origin_location stringnullable

    Origin of the shipment provided by the courier.

    destination_location stringnullable

    Destination of the shipment provided by the courier.

  • ]

Loading...