Shipment

The heart of the Integrated Services Platform are shipments. The definition of shipments consists of:

sender and recipient data
shipment (one or more), which will be physically shipped
selected service (optional added services)
other additional attributes dependent on user preference, eg.:
- Insurance
- Cash collection

To create a shipment ready for shipping, 3 steps are required:

Creating the shipment, consisting of recipient and sender details and information about the shipment itself (purple figures on the diagram below)
Downloading the information about the available services for the created shipment (blue figures on the diagram below),
Purchasing a label by selecting a service available for the shipment from step 1 (green figure on the diagram below)

Service prices may differ based on the shipment dimensions and parameters defined upon creation.

The list of all available services can be found in Shipment sizes and services

Service availability depends on the carriers with which the organization has signed contracts with.

For Clients whose agreement allows for a debit to be created in the InPost system (debit client), prices will not be returned to the JSON response to the request sent to the API.

On this page

1 Shipment creation diagram
2 Structure
3 Authentication
4 Shipment List

Shipment creation diagram

Structure

Shipment resource has the following attributes:

Attribute	Type	Description

Attribute	Type	Description
`id`	Integer	Read only. Shipment identifier in ShipX.
`status`	String	Read only. Current shipment status.
`tracking_number`	String	Shipment tracking number (logistic system ID).
`return_tracking_number`	String	Return shipment number. Will only appear if the shipment has received a status of `returned_to_sender`.
`service`	String	The service selected by the customer. Available values Shipment sizes and services.
`reference`	String	Additional shipment description, e.g. order or client ID
`is_return`	Boolean	Determines whether the shipment is a return.
`application_id`	Integer	Unique application identifier.
`created_by_id`	Integer	If of the user that created the shipment, if logged in.
`external_customer_id`	String	ID of the broker generating the shipment within a different organization.
`sending_method`	String	Duplicate of `custom_attributes`.
`end_of_week_collection`	Boolean	Determines if the shipment has a service “Service Weekend shipments”.
`comments`	String	Any comment.
`mpk`	String	Place of cost creation.
`additional_services`	Array[String]	Additional services selected when creating the shipment (different offers may contain different additional services). Available additional services: `sms`, `email`, `saturday`. Shipment sizes and services
`custom_attributes`	CustomAttributes	Additional, optional shipment attributes.
`cod`	MoneyData	Cash collection for the shipment.
`insurance`	MoneyData	Shipment insurance.
`sender`	Peer	Sender details.
`receiver`	Peer	Recipient details.
`selected_offer`	Offer	The service selected when buying the label.
`offers`	Array[Offer]	List of available services with prices, which can be purchased for the shipment.
`transactions`	Array[Transaction]	List of payment transactions related to the shipment.
`parcels`	Array[Parcel]	List of parcels within the shipment.
`created_at`	DateTime	Read only. Shipment creation date in ShipX.
`updated_at`	DateTime	Read only. Shipment update date in ShipX.

Parcel object attributes:

Attribute	Type	Description

Attribute	Type	Description
`id`	String	Required when creating a shipment with multiple parcels. Unique parcel ID within the shipment that allows for validation errors to be returned in connection to a specific parcel. ID is not persisted in the database and is not returned as an attribute of an already created shipment.
`template`	String	Predefined dimension and weight template name. The list of predefined dimension and weight templates can be found in Shipment sizes and services
`dimensions`	Object	Shipment dimensions. `length` `width` `height` `unit` - unit of shipment dimensions measure. Currently only mm (millimeters) Filled automatically when selecting a valid `template`.
`weight`	Object	Shipment weight `amount` - weight, `unit` - unit of shipment weight measure. Currently only kg (kilograms) Filled automatically when selecting a valid `template`.
`tracking_number`	String	Shipment tracking number. Assigned when buying a selected offer.
`is_non_standard`	Bool	Set to `true` when the shipment is non-standard. Parameter available only for courier services. Parcel handled only within the domestic courier services, in which one of its dimensions exceeds 120 cm, or the sum of the dimensions (length + width + height) exceeds 220 cm. Additionally, parcels considered non-standard are: round, cylindrical or oval, irregular shaped and/or with protruding elements. The option of non-standard parcels does not apply to log parcels.

Offer object attributes:

Attribute	Type	Description

Attribute	Type	Description
`id`	Integer	Unique offer identifier in the context of the shipment.
`service`	Service	Offered service object.
`carrier`	Carrier	Carrier object.
`additional_services`	Array[String]	Additional services selected when creating the shipment - available within the offer.
`status`	String	Offer status. Available offer statuses: `in_preparation`, `available`, `unavailable, selected, bought, expired`
`expires_at`	DateTime	Date and time when the offer expires.
`rate`	Decimal	Service price.
`currency`	String	Currency of the service price.
`unavailability_reasons`	Array	Offer unavailability reasons.

Service object attributes:

Attribute	Type	Description

Attribute	Type	Description
`id`	String	Service ID
`name`	String	Service name
`description`	String	Service description

Carrier object attributes:

Attribute	Type	Description

Attribute	Type	Description
`id`	String	Carrier ID
`name`	String	Carrier name
`description`	String	Carrier description

Transaction object attributes:

Attribute	Type	Description

Attribute	Type	Description
`id`	String	Transaction ID
`status`	String	Transaction status. Available statuses: `initiated`, `success`, `failure`
`created_at`	DateTime	Transaction creation date and time.
`updated_at`	DateTime	Last transaction modification date and time.
`offer_id`	Integer	ID of the offer connected to the transaction.

Peer object attributes:

Attribute	Type	Description

Attribute	Type	Description
`id`	String	Peer ID
`name`	String	Peer name
`company_name`	String	Company name
`first_name`	String	First name
`last_name`	String	Last name
`email`	String	E-mail address
`phone`	String	Telephone number
`address`	Address	Address

Address: object attributes:

line1 and line2 attributes are still supported, however, usage of street and building number is recommended.

Attribute	Type	Description

Attribute	Type	Description
`id`	String	Address ID
line1	String	Address first line
line2	String	Address second line
`street`	String	Street name
`building_number`	String	Building number
`city`	String	City
`post_code`	String	Postal code
`country_code`	String	Country code

MoneyData object attributes:

Attribute	Type	Description

Attribute	Type	Description
`amount`	Decimal	Amount
`currency`	String	Currency

CustomAttributes object attributes:

Attribute	Type	Description

Attribute	Type	Description
`target_point`	String	Target point name to which the shipment is to be delivered to, from which the recipient will collect it from. e.g. parcel locker name. Only locker shipments.
`sending_method`	String	Sending method Required for Allegro shipments.
`dropoff_point`	String	Dropoff point name to which the sender will deliver the shipment, e.g. parcel locker name. Required for the following sending methods: `pok`, `courier_pok`, `parcel_locker`.
`allegro_transaction_id`	String	Transaction number of the Allegro after-sale form in which the buyer has chosen the Allegro Paczkomat® InPost delivery method. The provision of this parameter will require provision of the `allegro_user_id` parameter.
`allegro_user_id`	String	Allegro user number within the transaction specified by the `allegro_user_id` parameter, which is the seller. The provision of this parameter will require provision of the allegro_transaction_id parameter.
`dispatch_order_id`	Integer	Dispatch order id. Read-only attribute, present when the shipment has a defined dispatch order.

Shipment resource example in JSON format (parcel locker shipment).

{
    "href": "https://api-shipx-pl.easypack24.net/v1/shipments/12345",
    "id": 12345,
    "status": "created",
    "tracking_number": null,
    "return_tracking_number": null,
    "service": "inpost_locker_standard",
    "reference": "Test",
    "is_return": false,
    "application_id": 25,
    "created_by_id": null,
    "external_customer_id": "8877xxx",
    "sending_method": "dispatch_order",
    "end_of_week_collection": false,
    "comments": null,
    "mpk": null,
    "additional_services": [],
    "custom_attributes": {
        "target_point": "KRA012",
        "sending_method": "dispatch_order"
    },
    "cod": {
        "amount": 12.5,
        "currency": "PLN"
    },
    "insurance": {
        "amount": 25.0,
        "currency": "PLN"
    },
    "sender": {
        "id": 12345,
        "name": "Name",
        "company_name": "Company_name",
        "first_name": "first_name",
        "last_name": "last_name",
        "email": "test@grupainteger.pl",
        "phone": "321321321",
        "address": {
            "id": 1764397634,
            "street": "Czerniakowska",
            "building_number": "87A",
            "line1": null,
            "line2": null,
            "city": "Warszawa",
            "post_code": "00-718",
            "country_code": "PL"
        }
    },
    "receiver": {
        "id": 12345,
        "name": "Name",
        "company_name": "Company name",
        "first_name": "Jan",
        "last_name": "Kowalski",
        "email": "test@inpost.pl",
        "phone": "111222333",
        "address": null
    },
    "selected_offer": null,
    "offers": [],
    "transactions": [],
    "parcels": [
        {
            "id": 12345,
            "identify_number": null,
            "tracking_number": null,
            "is_non_standard": false,
            "template": "small",
            "dimensions": {
                "length": 380.0,
                "width": 640.0,
                "height": 80.0,
                "unit": "mm"
            },
            "weight": {
                "amount": 25.0,
                "unit": "kg"
            }
        }
    ],
    "created_at": "2023-08-16T10:53:47.958+02:00",
    "updated_at": "2023-08-16T10:53:47.958+02:00"
}

Authentication

Access to the resource requires a valid access token.

Shipment List

Shipment List within the organization.

To retrieve the shipment list for a given organization the user has to be its member.

GET /v1/organizations/:organization_id/shipments

Example request

curl -X GET https://api-shipx-pl.easypack24.net/v1/organizations/1/shipments -H 'Authorization: Bearer token' -H 'Content-Type: application/json'

Response