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:

  1. Creating the shipment, consisting of recipient and sender details and information about the shipment itself (purple figures on the diagram below)

  2. Downloading the information about the available services for the created shipment (blue figures on the diagram below),

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

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.


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 .

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.

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 

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

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