[1.23.0] Shipment

Warning!

The resource is available only in the following countries: PL, IT

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 [1.23.0] Shipment sizes and servicesarchived

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	Availability

Attribute	Type	Description	Availability
`id`	Integer	Read only. Shipment identifier in ShipX.	PL, IT
`status`	String	Read only. Current shipment status.	PL, IT
`custom_attributes`	CustomAttributes	Additional, optional shipment attributes.	PL, IT
`parcels`	Array[Parcel]	List of parcels within the shipment.	PL, IT
`created_at`	DateTime	Read only. Shipment creation date in ShipX.	PL, IT
`created_by_id`	Integer	If of the user that created the shipment, if logged in.	PL, IT
`sender`	Peer	Sender details.	PL, IT
`receiver`	Peer	Recipient details.	PL, IT
`cod`	MoneyData	Cash collection for the shipment.	PL
`insurance`	MoneyData	Shipment insurance.	PL
`additional_services`	Array[String]	Additional services selected when creating the shipment (different offers may contain different additional services). Available additional services: `sms`, `email`, `saturday`. [1.23.0] Shipment sizes and servicesarchived	PL, IT
`reference`	String	Additional shipment description, e.g. order or client ID	PL, IT
`is_return`	Bool	Determines whether the shipment is a return.	PL, IT
`offers`	Array[Offer]	List of available services with prices, which can be purchased for the shipment.	PL, IT
`selected_offer`	Offer	The service selected when buying the label.	PL, IT
`transactions`	Array[Transaction]	List of payment transactions related to the shipment.	PL, IT
`tracking_number`	String	Shipment tracking number (logistic system ID).	PL, IT
`sending_method`	String	Duplicate of `custom_attributes`.	PL, IT
`external_customer_id`	String	ID of the broker generating the shipment within a different organization.	PL, IT

Parcel object attributes:

Attribute	Type	Description	Availability

Attribute	Type	Description	Availability
`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.	PL, IT
`template`	String	Predefined dimension and weight template name. The list of predefined dimension and weight templates can be found in [1.23.0] Shipment sizes and servicesarchived	PL, IT
`dimensions`	Object	Shipment dimensions. `length` `width` `height` `unit` - unit of shipment dimensions measure. Currently only mm (millimeters) Filled automatically when selecting a valid `template`.	PL, IT
`weight`	Object	Shipment weight `amount` - weight, `unit` - unit of shipment weight measure. Currently only kg (kilograms) Filled automatically when selecting a valid `template`.	PL, IT
`tracking_number`	String	Shipment tracking number. Assigned when buying a selected offer.	PL, IT
`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.	PL, IT

Offer object attributes:

Attribute	Type	Description	Availability

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

Service object attributes:

Attribute	Type	Description	Availability

Attribute	Type	Description	Availability
`id`	String	Service ID	PL, IT
`name`	String	Service name	PL, IT
`description`	String	Service description	PL, IT

Carrier object attributes:

Attribute	Type	Description	Availability

Attribute	Type	Description	Availability
`id`	String	Carrier ID	PL, IT
`name`	String	Carrier name	PL, IT
`description`	String	Carrier description	PL, IT

Transaction object attributes:

Attribute	Type	Description	Availability

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

Peer object attributes:

Attribute	Type	Description	Availability

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

Address: object attributes:

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

Attribute	Type	Description	Availability

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

MoneyData object attributes:

Attribute	Type	Description	Availability

Attribute	Type	Description	Availability
`amount`	Decimal	Amount	PL, IT
`currency`	String	Currency	PL, IT

CustomAttributes object attributes:

Attribute	Type	Description	Availability

Attribute	Type	Description	Availability
`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.	PL, IT
`sending_method`	String	[1.23.0] Sending Methodarchived Required for Allegro shipments.	PL, IT
`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`.	PL, IT
`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.	PL
`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.	PL
`dispatch_order_id`	Integer	Dispatch order id. Read-only attribute, present when the shipment has a defined dispatch order.	PL

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

{
	"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.

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