Passa al contenuto principale

Create shipment

POST 
/shipments

Create a new shipment and start tracking it with the specified courier. The list of couriers is available in the Supported couriers page or it can be retrieved from the API using the Get couriers list endpoint.

The API returns immediately after the shipment creation but tracking details are fetched by our systems after a few seconds. Therefore the shipment status returned in the response will be unknown and many fields will be null. To get the updated shipment details, use the Get shipment details endpoint, or the Get shipments list endpoint with appropriate filters, at a later time.

Tip

The courier is not mandatory. If not specified, the courier will be automatically detected based on the tracking code.

If a recipient email address is specified, email notifications will be sent for relevant shipment status changes. Notifications are enabled only when the shipment type is set to send.

Shipments created via the API always use the default sender. If you need to choose a different sender for shipments created through the API, contact us.

Request​

Body

required

Shipment data and optional recipient information.

    tracking_code stringrequired

    Possible values: Value must match regular expression ^[a-zA-Z0-9]{4,34}$

    Tracking code of the shipment.

    courier string

    Courier slug. If not specified, the courier will be automatically detected. The list of couriers is available in the Supported couriers page.

    type ShipmentType (string)

    Possible values: [send, receive]

    Default value: send

    Shipment type. In receive mode, recipient information is ignored and no email notifications will be sent.

    order_number string

    Possible values: <= 100 characters

    Order number associated with the shipment.

    description string

    Possible values: <= 1000 characters

    Additional notes about the shipment that will be visible only to the account owner.

    recipient_name string

    Possible values: <= 100 characters

    Name of the recipient of the shipment.

    recipient_email email

    Possible values: <= 100 characters

    Email of the recipient. If specified, the recipient will receive email notifications when the shipment status changes.

Responses​

Details of the newly created shipment.

Schema

    data

    object

    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...