Page Comparison

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)

Info

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.9.1] Shipment sizes and services

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

Table of Contents

Shipment creation diagram

Image Removed

Image Added

Structure

Shipment resource has the following attributes:

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`. [1.9.1] Shipment sizes and services
`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
`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 [1.9.1] Shipment sizes and services
`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
`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
`id`	String	Service ID
`name`	String	Service name
`description`	String	Service description

Carrier object attributes:

Attribute	Type	Description
`id`	String	Carrier ID
`name`	String	Carrier name
`description`	String	Carrier description

Transaction object attributes:

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
`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:

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

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
`amount`	Decimal	Amount
`currency`	String	Currency

CustomAttributes object attributes:

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	[1.8.1] Sending method 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).

Code Block

language	json

{
	"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",
}

Shipment List

Shipment List within the organization.

Info
To retrieve the shipment list for a given organization the user has to be its member.

Code Block

language	json

GET /v1/organizations/:organization_id/shipments

Example request

Code Block

language	json

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

Response

Code Block

language	json

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",
  }]
}

Note

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.

Versions Compared

Old Version 11

New Version 12

Key

Shipment creation diagram

Structure

Authentication

Shipment List