Shipment creation in offer mode

The shipment object is used to obtain available offers, and at the same time it represents the physical pack (or parcels) which will be sent between the stated addresses.


Access to the resource requires a valid access token.

Shipment creation in offer mode

In order to create a shipment within an organization the user has to be its member.

Attention! Debit customers

After creating a shipment we do not return prices for debit clients. The rate attribute is null

Attention! Asynchronous operation

After creation of the shipment, the asynchronous process of preparing offers, manifesting and buying the offer will be triggered.

POST /v1/organizations/:organization_id/shipments


All the following attributes should be included in the  shipment object.











Receiver details

The attribute is required.

  • In case of a courier service offer (inpost_courier_c2c included), at least receiver.company_name and/or receiver.first_name and receiver.last_name and address  object should be provided

  • In case of parcel locker service offer receiver.phone_number and  should be provided

  • Providing all the data will allow both types of offers to be presented

  • In case of is_return = true, Attribute receiver is not required



Sender details.

The attribute is optional.

  • If no data is provided the organization data for which the shipment is created will be used by default



Details of parcels in the shipment.

  • The attribute is required.

    • Minimum length - 1, maximum length - 1000



Additional shipment attributes, e.g.

"custom_attributes": {
"target_point": "KRA010"

The attribute is optional.

  • The list of available custom attributes has been described in Shipment.

  • Specifying a target point is required in case of a parcel locker service.



Cash collection amount.

The attribute is optional.

  • Attribute validation and requirement is defined at the time of providing a service.



Shipment insurance amount.

The attribute is required for the following services:
inpost_courier_standard, inpost_courier_express_1000, inpost_courier_express_1200, inpost_courier_express_1700, inpost_courier_palette when passing the COD attribute.

  • Attribute validation and requirement is defined at the time of providing a service.



Additional shipment description, e.g. order number.

The attribute is optional.

  • Minimum length - 3, maximum length - 100, can be empty.



Determines whether the shipment is a return shipment.

The attribute is optional.

  • Available values (true, false)

  • Can be empty.

  • If true, marks the shipment as a return shipment. In this case the recipient and sender details will be swapped automatically.



Additional services.

Available additional services: smsemailsaturday.

The attribute is optional.

  • Attribute validated once value is provided.

  • When the additional_services  attribute is provided, the system checks the service  attribute provision, if the service  attribute is not provided or the additional_services  attribute does not fit in the scope of the service  provided, the user will get an error.



ID of the broker generating shipments within a different organization.

The attribute is optional.



Setting the parameter to true results in the offer being selected for the given service but not being paid for. The shipment has to be paid for before the offer expiry. This parameter can also be set for each individual consignment (in this case the parameter set in the consignment has a higher priority).

The attribute is optional.

  • Default false



Name of cost center.

The attribute is optional.

  • Maximum length - 255

  • If the attribute is specified, we verify whether it belongs to the organization which the request is made from

  • Can be empty

The cost center must first be added to the organization in order to assign it to the shipment.



Any comment

The attribute is optional.

  • Maximum length - 100

  • Minimum length - 3

  • Can be empty

Example request with one parcel:

curl -X POST -H 'Authorization: Bearer token' -H 'Content-Type: application/json' -d '{ "mpk":"miejsce_powstania_kosztow", "comments": "dowolny komentarz",   "external_customer_id": "8877xxx", "receiver": { "first_name": "Jan", "last_name": "Kowalski", "name": "Nazwa", "email": "", "phone": "888000000", "address": { "id": "123", "street": "Malborska", "building_number": "130", "city": "Kraków", "post_code": "30-624", "country_code": "PL" } }, "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" }, "insurance": { "amount": 25, "currency": "PLN" }, "cod": { "amount": 12.50, "currency": "PLN" }, "additional_services": ["email", "sms"] }'


HTTP/1.1 201 CREATED Content-Type: application/json  { "href": "", "id": "1234567890", "status": "created", "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 } ], "external_customer_id": "8877xxx", "mpk": { "id": 1, "name": "miejsce_powstania_kosztow" }, "comments": "dowolny komentarz",   "custom_attributes": { "target_point": "KRA010", "open_code": null, "dropoff_point": null, "sending_method": "parcel_locker" }, "sender": { "id": "123", "name": "Nazwa", "company_name": "InPost S.A.", "first_name": "Jan", "last_name": "Nowak", "email": "", "phone": "888000000", "address": { "id": "123", "street": "Malborska", "building_number": "130, "city": "Kraków", "post_code": "30-624", "country_code": "PL" } }, "receiver": { "id": "1234", "name": "Nazwa", "company_name": null, "first_name": "Jan", "last_name": "Kowalski", "email": "", "phone": "888000000", "address": null }, "created_at": "2015-09-06T19:21:00.000+02:00", "created_by_id": 3,  "cod_amount": { "amount": 12.50, "currency": "PLN" }, "insurance": { "amount": 25, "currency": "PLN" }, "additional_services": ["email", "sms"], "reference": "Order No. 12345", "is_return": false, "tracking_number": null, "offers": [], "selected_offer": null, "transactions": [], "mpk": { "id": 1, "name": "Nazwa miejsca powstania kosztów." } }

Example request for multiple parcels in a single shipment (available only for inpost_courier):


Error information

Errors that may appear when creating a shipment (the following errors are returned as a response to the shipment creation request, not via webhooks):

  • validation_failed - request parameters are incorrect. Details are available in the details,

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

  • no_carriers - In case the organization has no carriers contracted,

  • carrier_unavailable - In case the organization has no carriers contracted providing the requested service


Asynchronous offer preparation

After creating a shipment an asynchronous offer preparation process starts. The offer expires after 5 minutes and they won't be buyable anymore. To generate a new offer, an empty edit request to the shipment should be made.

To receive information about the offers preparation process finishing, a url address should be added to the organization configuration to receive the offers_prepared  events. Thanks to that ShipX will send the following information to the url on offers preparation process finishing: