The shipment object is used to obtain available offers, and at the same time it represents the physical parcel (or parcels) which will be sent between the stated addresses.
POST /v1/organizations/:organization_id/shipments
Rights
To create a shipment within the given organization, the user needs to be a member thereof.
Parameters
All the following parameters should be included in the object shipment object.
| Parameter | Type | Description | Validation |
|---|---|---|---|
receiver | ReceiverForm | Parcel recipient's data | The attribute is required. • in the case a courier service offer is to be presented (together with inpost_courier_c2c) at least receiver.company_name and/or receiver.first_name receiver.last_name and the address object should be provided |
sender | SenderForm | Parcel sender's data. | The attribute is not required. • If no data are provided, the data of the organization under which the shipment is being created will be used by default. |
parcels | Array[ParcelsSimpleForm] | Data of the parcels included in the shipment. | The attribute is required. • Collection minimum 1, maximum 1000 |
custom_attributes | CustomAttributesForm | Additional shipment attributes, e.g.
| The attribute is not required. • The list of additional attributes has been described in the introduction. |
cod | CodForm | Collection amount. | The attribute is not required. • Attribute validation and required provision are defined at the time of providing the service. |
insurance | InsuranceForm | Shipment insurance amount. | The attribute is not required. • Attribute validation and required provision are defined at the time of providing the service. |
reference | String | Additional shipment description, e.g. order number. | The attribute is not required. • Minimum 3 characters, maximum 100 characters, possibility to provide an empty attribute. |
is_return | Bool | Determines the shipment as a return shipment. | The attribute is not required. • Acceptable values • Possibility to provide an empty attribute.(true, false) |
service | String | Service selected by the client. Available values see API X Rozmiary i usługi dla przesyłek. | The attribute is required. |
additional_services | Array[String] | Additional services. Available additional services: | The attribute is not required. |
external_customer_id | String | ID of the broker generating shipments within a different organization. | The attribute is not required. |
only_choice_of_offer | Boolean | Setting of the parameter to true does not result in the offer being selected for the stated service, but it will not be automatically paid. Such shipment has to be paid for before the end of the offer's validity term by completing the operations (Opłacanie przesyłki) | The attribute is not required. |
mpk | String | Name of cost center. | The attribute is not required. • maximum 255 characters |
comments | String | Any comment | The attribute is not required • maximum 100 characters |
Note! Debit clients
After creating a shipment, we do not return prices for debit clients.
The rate attribute takes the null value
Sample requests
Sample request for a courier shipment
POST /v1/organizations/123/shipments HTTP/1.1
Host: https://api-shipx-pl.easypack24.net
Content-Type: application/json
Authorization: Bearer lkfjasd9f70y43ohriw...[ommited for brevity]...
{
"receiver": {
"name": "Name",
"company_name": "Company name",
"first_name": "Jan",
"last_name": "Kowalski",
"email": "receiver@example.com",
"phone": "888000000",
"address": {
"street": "Cybernetyki",
"building_number": "10",
"city": "Warszawa",
"post_code": "02-677",
"country_code": "PL"
}
},
"parcels": [
{
"id": "small package",
"dimensions": {
"length": "80",
"width": "360",
"height": "640",
"unit": "mm"
},
"weight": {
"amount": "25",
"unit": "kg"
},
"is_non_standard": false
}
],
"insurance": {
"amount": 25,
"currency": "PLN"
},
"cod": {
"amount": 12.50,
"currency": "PLN"
},
"service": "inpost_courier_standard",
"additional_services": ["email", "sms"],
"reference": "Test",
"comments": "dowolny komentarz",
"external_customer_id": "8877xxx",
"mpk": "Nazwa miejsca powstania kosztów"
}
In the response the server will return status 201 along with the newly created shipment object.
HTTP/1.1 201 CREATED
Content-Type: application/json
{
"href": "https://api-shipx-pl.easypack24.net/v1/shipments/1234567890",
"id": 1234567890,
"status": "created",
"tracking_number": null,
"service": "inpost_courier_standard",
"reference": "Test",
"is_return": false,
"application_id": 123,
"created_by_id": null,
"external_customer_id": "8877xxx",
"sending_method": null,
"mpk": {
"id": 1,
"name": "Nazwa miejsca powstania kosztów"
},
"comments": "dowolny komentarz",
"additional_services": [
"email",
"sms"
],
"custom_attributes": {},
"cod": {
"amount": 12.5,
"currency": "PLN"
},
"insurance": {
"amount": 25.0,
"currency": "PLN"
},
"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",
"line1": null,
"line2": null
"city": "Kraków",
"post_code": "30-624",
"country_code": "PL"
}
},
"receiver": {
"id": 123,
"name": "Name",
"company_name": "Company name",
"first_name": "Jan",
"last_name": "Kowalski",
"email": "receiver@example.com",
"phone": "888000000",
"address": {
"id": 123,
"street": "Malborska",
"building_number": "130",
"line1": null,
"line2": null,
"city": "Kraków",
"post_code": "30-624",
"country_code": "PL"
}
},
"selected_offer": null,
"offers": [],
"transactions": [],
"parcels": [
{
"id": 123,
"tracking_number": null,
"is_non_standard": false,
"template": null,
"dimensions": {
"length": 80.0,
"width": 360.0,
"height": 640.0,
"unit": "mm"
},
"weight": {
"amount": 25.0,
"unit": "kg"
}
}
],
"end_of_week_collection": false,
"created_at": "2020-02-23T18:07:08.967+01:00",
"updated_at": "2020-02-23T18:07:08.967+01:00"
}
Sample request with many parcels (multi-packs may be created only for inpost_courier):
POST /v1/organizations/123/shipments HTTP/1.1
Host: https://api-shipx-pl.easypack24.net
Content-Type: application/json
Authorization: Bearer lkfjasd9f70y43ohriw...[ommited for brevity]...
{
"receiver": {
"name": "Name",
"company_name": "Company name",
"first_name": "Jan",
"last_name": "Kowalski",
"email": "receiver@example.com",
"phone": "888000000",
"address": {
"street": "Cybernetyki",
"building_number": "10",
"city": "Warszawa",
"post_code": "02-677",
"country_code": "PL"
}
},
"parcels": [
{
"id": "small package",
"dimensions": {
"length": "80",
"width": "360",
"height": "640",
"unit": "mm"
},
"weight": {
"amount": "25",
"unit": "kg"
},
"is_non_standard": true
},
{
"id": "big package",
"dimensions": {
"length": "80",
"width": "360",
"height": "640",
"unit": "mm"
},
"weight": {
"amount": "25",
"unit": "kg"
},
"is_non_standard": true
}
],
"insurance": {
"amount": 25,
"currency": "PLN"
},
"cod": {
"amount": 12.50,
"currency": "PLN"
},
"service": "inpost_courier_standard",
"additional_services": ["email", "sms"],
"reference": "Test",
"comments": "dowolny komentarz",
"external_customer_id": "8877xxx",
"mpk": "Nazwa miejsca powstania kosztów"
}
In the response the server will return status 201 along with the newly created shipment object.
HTTP/1.1 201 CREATED
Content-Type: application/json
{
"href": "https://api-shipx-pl.easypack24.net/v1/shipments/1234567890",
"id": 1234567890,
"status": "created",
"tracking_number": null,
"service": "inpost_courier_standard",
"reference": "Test",
"is_return": false,
"application_id": 123,
"created_by_id": null,
"external_customer_id": "8877xxx",
"sending_method": null,
"mpk": {
"id": 1,
"name": "Nazwa miejsca powstania kosztów"
},
"comments": "dowolny komentarz",
"additional_services": [
"email",
"sms"
],
"custom_attributes": {},
"cod": {
"amount": 12.5,
"currency": "PLN"
},
"insurance": {
"amount": 25.0,
"currency": "PLN"
},
"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",
"line1": null,
"line2": null
"city": "Kraków",
"post_code": "30-624",
"country_code": "PL"
}
},
"receiver": {
"id": 123,
"name": "Name",
"company_name": "Company name",
"first_name": "Jan",
"last_name": "Kowalski",
"email": "receiver@example.com",
"phone": "888000000",
"address": {
"id": 509576837,
"street": "Cybernetyki",
"building_number": "10",
"line1": null,
"line2": null,
"city": "Warszawa",
"post_code": "02-677",
"country_code": "PL"
}
},
"selected_offer": null,
"offers": [],
"transactions": [],
"parcels": [
{
"id": 123,
"tracking_number": null,
"is_non_standard": true,
"template": null,
"dimensions": {
"length": 80.0,
"width": 360.0,
"height": 640.0,
"unit": "mm"
},
"weight": {
"amount": 25.0,
"unit": "kg"
}
},
{
"id": 123,
"tracking_number": null,
"is_non_standard": true,
"template": null,
"dimensions": {
"length": 80.0,
"width": 360.0,
"height": 640.0,
"unit": "mm"
},
"weight": {
"amount": 25.0,
"unit": "kg"
}
}
],
"end_of_week_collection": false,
"created_at": "2020-02-23T18:22:57.378+01:00",
"updated_at": "2020-02-23T18:22:57.378+01:00"
}
Sample standard parcel station shipment creation request.
POST /v1/organizations/123/shipments HTTP/1.1
Host: https://api-shipx-pl.easypack24.net
Content-Type: application/json
Authorization: Bearer lkfjasd9f70y43ohriw...[ommited for brevity]...
{
"receiver": {
"name": "Name",
"company_name": "Company name",
"first_name": "Jan",
"last_name": "Kowalski",
"email": "test@inpost.pl",
"phone": "111222333"
},
"parcels":
{
"template": "small"
},
"insurance": {
"amount": 25,
"currency": "PLN"
},
"cod": {
"amount": 12.50,
"currency": "PLN"
},
"custom_attributes": {
"sending_method": "dispatch_order",
"target_point": "KRA012"
},
"service": "inpost_locker_standard",
"reference": "Test",
"external_customer_id": "8877xxx"
}
In the response the server will return status 201 along with the newly created shipment object.
HTTP/1.1 201 CREATED
Content-Type: application/json
{
"href": "https://api-shipx-pl.easypack24.net/v1/shipments/1234567890",
"id": 1234567890,
"status": "created",
"tracking_number": null,
"service": "inpost_locker_standard",
"reference": "Test",
"is_return": false,
"application_id": 123,
"created_by_id": null,
"external_customer_id": "8877xxx",
"sending_method": "dispatch_order",
"mpk": null,
"comments": null,
"additional_services": [],
"custom_attributes": {
"sending_method": "dispatch_order",
"target_point": "KRA012"
},
"cod": {
"amount": 12.5,
"currency": "PLN"
},
"insurance": {
"amount": 25.0,
"currency": "PLN"
},
"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",
"line1": null,
"line2": null
"city": "Kraków",
"post_code": "30-624",
"country_code": "PL"
}
},
"receiver": {
"id": 123,
"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": 123,
"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"
}
}
],
"end_of_week_collection": false,
"created_at": "2020-02-23T18:17:40.073+01:00",
"updated_at": "2020-02-23T18:17:40.073+01:00"
}
Sample request for an Allegro Paczkomaty24/7 InPost shipment
POST /v1/organizations/123/shipments HTTP/1.1
Host: https://api-shipx-pl.easypack24.net
Content-Type: application/json
Authorization: Bearer lkfjasd9f70y43ohriw...[ommited for brevity]...
{
"receiver": {
"name": "Name",
"company_name": "Company name",
"first_name": "Jan",
"last_name": "Kowalski",
"email": "123abc+123abc@user.allegrogroup.pl",
"phone": "111222333"
},
"parcels":
{
"template": "small"
},
"custom_attributes": {
"target_point": "KRA012",
"sending_method": "dispatch_order"
},
"service": "inpost_locker_allegro"
}
In the response the server will return status 201 along with the newly created shipment object.
HTTP/1.1 201 CREATED
Content-Type: application/json
{
"href": "https://api-shipx-pl.easypack24.net/v1/shipments/1234567890",
"id": 1234567890,
"status": "created",
"tracking_number": null,
"service": "inpost_locker_allegro",
"reference": null,
"is_return": false,
"application_id": 123,
"created_by_id": null,
"external_customer_id": null,
"sending_method": "dispatch_order",
"mpk": null,
"comments": null,
"additional_services": [],
"custom_attributes": {
"sending_method": "dispatch_order",
"target_point": "KRA012"
},
"cod": {
"amount": null,
"currency": null
},
"insurance": {
"amount": 5000,
"currency": "PLN"
},
"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",
"line1": null,
"line2": null
"city": "Kraków",
"post_code": "30-624",
"country_code": "PL"
}
},
"receiver": {
"id": 123,
"name": "Name",
"company_name": "Company name",
"first_name": "Jan",
"last_name": "Kowalski",
"email": "123abc+123abc@user.allegrogroup.pl",
"phone": "111222333",
"address": null
},
"selected_offer": null,
"offers": [],
"transactions": [],
"parcels": [
{
"id": 123,
"tracking_number": null,
"is_non_standard": false,
"template": "small",
"dimensions": {
"length": 380.0,
"width": 640.0,
"height": 80.0,
"unit": "mm"
},
"weight": {
"amount": 10.0,
"unit": "kg"
}
}
],
"end_of_week_collection": false,
"created_at": "2020-02-23T18:52:25.100+01:00",
"updated_at": "2020-02-23T18:52:25.100+01:00"
}
Sample request for an Allegro miniKurier24 InPost shipment.
POST /v1/organizations/123/shipments HTTP/1.1
Host: https://api-shipx-pl.easypack24.net
Content-Type: application/json
Authorization: Bearer lkfjasd9f70y43ohriw...[ommited for brevity]...
{
"receiver": {
"name": "Name",
"company_name": "Company name",
"first_name": "Jan",
"last_name": "Kowalski",
"email": "123abc+123abc@user.allegrogroup.pl",
"phone": "888000000",
"address": {
"street": "Cybernetyki",
"building_number": "10",
"city": "Warszawa",
"post_code": "02-677",
"country_code": "PL"
}
},
"parcels":
{
"template": "letter_a"
},
"custom_attributes": {
"sending_method": "dispatch_order"
},
"service": "inpost_letter_allegro"
}
In the response the server will return status 201 along with the newly created shipment object.
HTTP/1.1 201 CREATED
Content-Type: application/json
{
"href": "https://api-shipx-pl.easypack24.net/v1/shipments/1234567890",
"id": 1234567890
"status": "created",
"tracking_number": null,
"service": "inpost_letter_allegro",
"reference": null,
"is_return": false,
"application_id": 123,
"created_by_id": null,
"external_customer_id": null,
"sending_method": "dispatch_order",
"mpk": null,
"comments": null,
"additional_services": [],
"custom_attributes": {
"sending_method": "dispatch_order"
},
"cod": {
"amount": null,
"currency": null
},
"insurance": {
"amount": 5000,
"currency": "PLN"
},
"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",
"line1": null,
"line2": null
"city": "Kraków",
"post_code": "30-624",
"country_code": "PL"
}
},
"receiver": {
"id": 123,
"name": "Name",
"company_name": "Company name",
"first_name": "Jan",
"last_name": "Kowalski",
"email": "123abc+123abc@user.allegrogroup.pl",
"phone": "888000000",
"address": {
"id": 123,
"street": "Cybernetyki",
"building_number": "10",
"line1": null,
"line2": null,
"city": "Warszawa",
"post_code": "02-677",
"country_code": "PL"
}
},
"selected_offer": null,
"offers": [],
"transactions": [],
"parcels": [
{
"id": 123,
"tracking_number": null,
"is_non_standard": false,
"template": "letter_a",
"dimensions": {
"length": 380.0,
"width": 640.0,
"height": 80.0,
"unit": "mm"
},
"weight": {
"amount": 10.0,
"unit": "kg"
}
}
],
"end_of_week_collection": false,
"created_at": "2020-02-23T19:24:51.120+01:00",
"updated_at": "2020-02-23T19:24:51.120+01:00"
}
Sample request for an Allegro Kurier24 InPost shipment
POST /v1/organizations/123/shipments HTTP/1.1
Host: https://api-shipx-pl.easypack24.net
Content-Type: application/json
Authorization: Bearer lkfjasd9f70y43ohriw...[ommited for brevity]...
{
"receiver": {
"name": "Name",
"company_name": "Company name",
"first_name": "Jan",
"last_name": "Kowalski",
"email": "gtcc1rh559+4fe361dc5@user.allegrogroup.pl",
"phone": "888000000",
"address": {
"street": "Cybernetyki",
"building_number": "10",
"city": "Warszawa",
"post_code": "02-677",
"country_code": "PL"
}
},
"parcels": {
"dimensions": {
"length": "10",
"width": "10",
"height": "10",
"unit": "mm"
},
"weight": {
"amount": "10",
"unit": "kg"
}
},
"cod": {
"amount": 12.50,
"currency": "PLN"
},
"custom_attributes": {
"sending_method": "dispatch_order"
},
"service": "inpost_courier_allegro"
}
In the response the server will return status 201 along with the newly created shipment object.
HTTP/1.1 201 CREATED
Content-Type: application/json
{
"href": "https://api-shipx-pl.easypack24.net/v1/shipments/1234567890",
"id": 1234567890,
"status": "created",
"tracking_number": null,
"service": "inpost_courier_allegro",
"reference": null,
"is_return": false,
"application_id": 123,
"created_by_id": null,
"external_customer_id": null,
"sending_method": "dispatch_order",
"mpk": null,
"comments": null,
"additional_services": [],
"custom_attributes": {
"sending_method": "dispatch_order"
},
"cod": {
"amount": 12.5,
"currency": "PLN"
},
"insurance": {
"amount": 5000,
"currency": "PLN"
},
"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",
"line1": null,
"line2": null
"city": "Kraków",
"post_code": "30-624",
"country_code": "PL"
}
},
"receiver": {
"id": 123,
"name": "Name",
"company_name": "Company name",
"first_name": "Jan",
"last_name": "Kowalski",
"email": "123abc+123abc@user.allegrogroup.pl",
"phone": "888000000",
"address": {
"id": 123,
"street": "Cybernetyki",
"building_number": "10",
"line1": null,
"line2": null,
"city": "Warszawa",
"post_code": "02-677",
"country_code": "PL"
}
},
"selected_offer": null,
"offers": [],
"transactions": [],
"parcels": [
{
"id": 123,
"tracking_number": null,
"is_non_standard": false,
"template": null,
"dimensions": {
"length": 10.0,
"width": 10.0,
"height": 10.0,
"unit": "mm"
},
"weight": {
"amount": 10.0,
"unit": "kg"
}
}
],
"end_of_week_collection": false,
"created_at": "2020-02-23T19:09:25.712+01:00",
"updated_at": "2020-02-23T19:09:25.712+01:00"
}
Note! Asynchronous action.
After creating a shipment, an asynchronous offer preparation, manifestation and offer purchase process will be started.
In order to obtain information about completing the process, the URL address (webhook) should be defined in the organization configuration, under which information is to be sent for offers_prepared and/or shipment_confirmed events. In this way, the ShipX application will send the information to the stated address.
Errors which may occur when creating a shipment (the following errors are sent to the application that has sent the request, not to the webhook):
validation_failed- sent parameters are incorrect. Details contained in the details field,resource_not_found- in the event that the user tries to create a shipment for an organization that does not exist or has no right to create it,no_carriers- in the event that the organization has no agreement signed with any carrier,carrier_unavailable- in the event that the organization has no agreement signed with a carrier providing the selected service specified in the service attribute.
Creating shipment size in the simplified mode, on the basis of the parameters sent
For sizes, read osobnym dokumencie
The application allows to generate a shipment with the size, without specifying its name. The size is generated on the basis of the parameters sent,
an example is available below:
"parcels": {
"dimensions": {
"length": "120",
"width": "34",
"height": "81",
"unit": "mm"
},
"weight": {
"amount": "20",
"unit": "kg"
} }
In order to find the proper shipment size, without specifying its name, it is necessary to provide all of the parameters of the dimensions and weight objects.
The table below presents the conditions to be met to generate the size on the basis of the parameters sent.
| Shipment size | Service | Parameter: Contractual intervals and their values |
|---|---|---|
letter_a |
|
|
small |
|
|
medium |
|
|
large |
|
|
palette | inpost_courier_palette |
|
parcel | inpost_courier_standard inpost_courier_express_1700 |
|
parcel | other services |
|