[1.9.0] 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 https://dokumentacja-inpost.atlassian.net/wiki/spaces/PL/pages/18153507

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.

custom_attributes

CustomAttributes

Additional, optional shipment attributes.

parcels

Array[Parcel]

List of parcels within the shipment.

created_at

DateTime

Read only. Shipment creation date in ShipX.

created_by_id

Integer

If of the user that created the shipment, if logged in.

sender

Peer

Sender details.

receiver

Peer

Recipient details.

cod

MoneyData

Cash collection for the shipment.

insurance

MoneyData

Shipment insurance.

additional_services

Array[String]

Additional services selected when creating the shipment (different offers may contain different additional services).

Available additional services: sms, email, saturday. https://dokumentacja-inpost.atlassian.net/wiki/spaces/PL/pages/18153507

reference

String

Additional shipment description, e.g. order or client ID

is_return

Bool

Determines whether the shipment is a return.

offers

Array[Offer]

List of available services with prices, which can be purchased for the shipment.

selected_offer

Offer

The service selected when buying the label.

transactions

Array[Transaction]

List of payment transactions related to the shipment.

tracking_number

String

Shipment tracking number (logistic system ID).

sending_method

String

Duplicate of custom_attributes.

external_customer_id 

String

ID of the broker generating the shipment within a different organization.

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  https://dokumentacja-inpost.atlassian.net/wiki/spaces/PL/pages/18153507

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

https://dokumentacja-inpost.atlassian.net/wiki/spaces/PL/pages/18153491

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

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 { "href": "https://api-shipx-pl.easypack24.net/v1/organizations/1/shipments/1234567890", "id": "1234567890", "status": "offers_prepared", "parcels": [ { "id": "small package", "template": "small", "dimensions": { "length": "80", "width": "360", "height": "640", "unit": "mm" }, "weight": { "amount": "25", "unit": "kg" }, "tracking_number": null, "is_non_standard": false } ], "custom_attributes": { "target_point": "KRA010", "dropoff_point": null, "sending_method": "parcel_locker", "dispatch_order_id": 1 }, "sender": { "id": "123", "name": "Nazwa", "company_name": "InPost S.A.", "first_name": "Jan", "last_name": "Nowak", "email": "sender@email.com", "phone": "888000000", "address": { "id": "123", "street": "Malborska", "building_number": "130", "city": "Kraków", "post_code": "30-624", "country_code": "PL" } }, "receiver": { "id": "123", "name": "Nazwa", "company_name": null, "first_name": null, "last_name": null, "email": "sender@email.com", "phone": "888000000", "address": null }, "created_at": "2015-09-06T19:21:00.000+02:00", "cod": { "amount": 12.50, "currency": "PLN" }, "insurance": { "amount": 25, "currency": "PLN" }, "additional_services": [], "reference": "Order No. 12345", "is_return": false, "tracking_number": null, "created_by_id": 3, "offers": [ { "id": 1278, "carrier": { "id": "inpost_locker", "name": "InPost Paczkomaty", "description": "InPost Paczkomaty - Przesyłki paczkomatowe." }, "service": { "id": "inpost_locker_standard", "name": "Paczkomatowa Standardowa", "description": "Przesyłka paczkomatowa standardowa." }, "status": "available", "expires_at": "2015-09-06T19:21:00.000+02:00", "rate": 2.02, "currency": "PLN", "unavailability_reasons": null } ], "selected_offer": null, "transactions": [], "sending_method": "parcel_locker", "external_customer_id": "8877xxx", }

 

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.

1 GET /v1/organizations/:organization_id/shipments

Example request

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

Response

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 HTTP/1.1 200 OK Content-Type: application/json   { "href": "https://api-shipx-pl.easypack24.net/v1/organizations/1/shipments", "count": 15, "per_page": 30, "page": 1, "items": [{     "href": "https://api-shipx-pl.easypack24.net/v1/organizations/1/shipments/1234567890",     "id": "1234567890",     "status": "offers_prepared",     "parcels": [         {             "id": "small package",             "template": "small",             "dimensions": {                 "length": "80",                 "width": "360",                 "height": "640",                 "unit": "mm"             },             "weight": {                 "amount": "25",                 "unit": "kg"             },             "tracking_number": null,             "is_non_standard": false         }     ],     "custom_attributes": {         "target_point": "KRA010",         "dropoff_point": null,         "sending_method": "parcel_locker",         "dispatch_order_id": 1     },     "sender": {         "id": "123",         "name": "Nazwa",         "company_name": "InPost S.A.",         "first_name": "Jan",         "last_name": "Nowak",         "email": "sender@email.com",         "phone": "888000000",         "address": {             "id": "123",             "street": "Malborska",             "building_number": "130",             "city": "Kraków",             "post_code": "30-624",             "country_code": "PL"         }     },     "receiver": {         "id": "123",         "name": "Nazwa",         "company_name": null,         "first_name": null,         "last_name": null,         "email": "sender@email.com",         "phone": "888000000",         "address": null     },     "created_at": "2015-09-06T19:21:00.000+02:00",     "cod": {         "amount": 12.50,         "currency": "PLN"     },     "insurance": {         "amount": 25,         "currency": "PLN"     },     "additional_services": [],     "reference": "Order No. 12345",     "is_return": false,     "tracking_number": null,     "created_by_id": 3,     "offers": [         {             "id": 1278,             "carrier": {                 "id": "inpost_locker",                 "name": "InPost Paczkomaty",                 "description": "InPost Paczkomaty - Przesyłki paczkomatowe."             },             "service": {                 "id": "inpost_locker_standard",                 "name": "Paczkomatowa Standardowa",                 "description": "Przesyłka paczkomatowa standardowa."             },             "status": "available",             "expires_at": "2015-09-06T19:21:00.000+02:00",             "rate": 2.02,             "currency": "PLN",             "unavailability_reasons": null         }     ],     "selected_offer": null,     "transactions": [],     "sending_method": "parcel_locker",     "external_customer_id": "8877xxx", }] }

 

Error information

Errors that may occur when retrieving the list of shipments

  • resource_not_found - Organization for which the shipments list was requested either doesn't exist or the user has no access to it.