Shipments API V2

Manage your dropshipping shipments and generate parcel labels for them

This API is only used in dropshipping shipments see tutorial getting started with Drop Shipping for suppliers. Shipments API allows your to view your shipments generated from sales orders, add status information to shipments (and orders), register your shipments with Posti, retrieve tracking codes for them, and generate parcel labels for them. Typically you will first register your shipment, and receive a tracking code (or multiple tracking codes, in there is more than one parcel) as a response. From then on, you can use the received tracking code to keep track of your shipment's status during its handling, transportation and delivery.

If you act as a supplier for a separate retailer, you will first fetch the shipments generated from retailer's sales orders and then continue the process as described above. The status information you add to your shipments will also be linked to the original sales order, so the retailer will also be able to track the status of the shipments related to their orders.

You can also generate parcel labels to be attached on the parcels, before you hand them over to Posti for transportation. The most straightforward way to achieve all of this is to perform the whole operation in one go, with one request. In this scenario, you would first authenticate yourself with Posti Authentication API, and then simply execute a single PUT request to URL /v2/shipments/, with a valid authentication header, and the information of your shipment in request body in JSON format. You will then get information about the generated shipment id, tracking code, and parcel label in the response.

As a final step, you would download the parcel label PDF from the provided URL, print it, attach it to your parcel, and hand it over to Posti for transportation. Then you would just wait for the parcel to be delivered, and use the tracking code to keep track of its status in the meanwhile.

As with other requests to the system, user must be authenticated as described in Posti Authentication API.

API Endpoints

Environment	Protocol	Host
Test	HTTPS	argon.ecom-api.posti.com
Prod	HTTPS	ecom-api.posti.com

Here is a list of all available API methods, followed by a detailed description for each one.

GET	/v2/shipments/{shipmentId}	Retrieve data of a single shipment
GET	/v2/shipments	Retrieve data of multiple shipments
POST	/v2/shipments/{shipmentId}	Update data of an existing shipment
POST	/v2/shipments/{shipmentId}/statuses	Add a status element to a shipment
GET	/v2/shipments/print/{documentType}/{shipmentId}/{parcelId}	Retrieve a print document in PDF-format eg. parcel label or delivery note

Overview

Retrieve data of a single shipment, identified by the shipment id.

Query string parameters

Parameter	Mandatory	Type	Description
with_product_details	no	String	Value 'true' or 'false'. Default value is 'false'. Should product details be returned as a part of the response message. (e.g. /v2/shipments/{shipmentId}/?with_product_details=true)

Response fields

Element		Type	Description
shipmentId		String	Unique shipment identifier.
clientReference		String	Warehouse's order id.
consignment.documentId		String	Unique identifier of the document in supplier's system.
consignment.metadata		Object	Meta data of the shipment.
consignment.metadata.sourceOrganization		String	Business ID of the retailer.
consignment.metadata.receiverOrganization		String	Business ID of the supplier.
consignment.metadata.creationDateTime		String	DateTime of creation, in ISO 8601 format (yyyy-MM-dd'T'HH:mm:ss.SSSZZ).
consignment.orderDate		String	Requested delivery date for the order. DateTime in ISO 8601 format (yyyy-MM-dd'T'HH:mm:ss.SSSZZ).
consignment.deliveryDateTime		String	Actual delivery date for the order. DateTime in ISO 8601 format (yyyy-MM-dd'T'HH:mm:ss.SSSZZ). Delivery date time is shown to Retailer at Glue UI e.g. it is not updated to order information available via Orders API.
consignment.comments		Array	Notes about the shipment e.g. comments.
consignment.comments[n].type		String	Note's type. Allowed values are "reference" and "passThrough".
consignment.comments[n].value		String	Note's text.
consignment.comments[n].name		String	Note's name. e.g. "senderReference2"
consignment.reference		String	Reference code for the consignment from the registrant's system. Typically an order number.
consignment.sender		Object	Sender of the shipment.
consignment.sender.externalId		String	Identifier of the sender in an external system.
consignment.sender.name		String	Name of the sender. May contain one linebreak (`\n`)
consignment.sender.streetAddress		String	Street address of the sender. May contain up to two linebreaks (`\n`)
consignment.sender.postalCode		String	Postal code of the sender
consignment.sender.postOffice		String	Post office of the sender
consignment.sender.country		String	Country of the sender
consignment.sender.telephone		String	Telephone number of the sender
consignment.sender.email		String	Email address of the sender
consignment.vendor		Object	Vendor of the shipment.
consignment.vendor.externalId		String	Identifier of the vendor in an external system.
consignment.vendor.name		String	Name of the vendor. May contain one linebreak (`\n`)
consignment.vendor.streetAddress		String	Street address of the vendor. May contain up to two linebreaks (`\n`)
consignment.vendor.postalCode		String	Postal code of the vendor
consignment.vendor.postOffice		String	Post office of the vendor
consignment.vendor.country		String	Country of the vendor
consignment.vendor.telephone		String	Telephone number of the vendor
consignment.vendor.email		String	Email address of the vendor
consignment.client	X	Object	Client information.
consignment.client.externalId		String	Identifier of the client in external system e.g. customer number
consignment.client.name	X	String	Name of the client. May contain one linebreak (`\n`).
consignment.client.streetAddress	X	String	Street address of the client. May contain up to two linebreaks (`\n`)
consignment.client.postalCode	X	String	Postal code of the client
consignment.client.postOffice	X	String	Post office of the client
consignment.client.country	X	String	2-letter country code of client as defined in ISO 3166-1 alpha-2, e.g. `FI`
consignment.client.telephone		String	Phone number of the client with country code e.g. +358501234567
consignment.client.email		String	Email of the client
consignment.recipient		Object	Recipient of the shipment
consignment.recipient.externalId		String	Identifier of the recipient in an external system.
consignment.recipient.name		String	Name of the recipient. May contain one linebreak (`\n`)
consignment.recipient.streetAddress		String	Street address of the recipient. May contain up to two linebreaks (`\n`)
consignment.recipient.postalCode		String	Postal code of the recipient
consignment.recipient.postOffice		String	Post office of the recipient
consignment.recipient.country		String	Country of the recipient
consignment.recipient.telephone		String	Telephone number of the recipient
consignment.recipient.email		String	Email address of the recipient
consignment.deliveryAddress		Object	Additional delivery address information, such as Smartpost
consignment.deliveryAddress.externalId		String	Identifier of the delivery address in an external system.
consignment.deliveryAddress.name	(X)	String	Name on the additional delivery address. May contain two linebreaks (`\n`). Example: `First name\nLast name\nPickup point name`
consignment.deliveryAddress.streetAddress	(X)	String	Street address of the additional delivery address. May contain up to two linebreaks (`\n`)
consignment.deliveryAddress.postalCode	(X)	String	Postal code of the additional delivery address
consignment.deliveryAddress.postOffice	(X)	String	Post office of the additional delivery address
consignment.deliveryAddress.country	(X)	String	2-letter country code of the additional delivery address as defined in ISO 3166-1 alpha-2, e.g. `FI`
consignment.deliveryAddress.telephone		String	Phone number for the delivery address with country code e.g. +358501234567
consignment.deliveryAddress.email		String	Email address for the delivery address
consignment.freightTermCode		String	Describes how the freight cost for a shipment of goods should be billed.
consignment.labelNotes		String	An additional informative text to be printed on the parcel label. This is optional.
consignment.paymentTerm		String	Payment term for the order, e.g. "Cash"
consignment.totalWholeSalePrice		Number	Total wholesale price of the order.
consignment.parcels		Array	Parcel(s) of the shipment. This can also mean cargo shipments.
consignment.parcels[n].reference		String	Reference code for the specific parcel from registrant's system. Optional.
consignment.parcels[n].packageType		String	Type of package. `PC` means normal parcel or letter.
consignment.parcels[n].serviceCode		String	This code identifies the transportation service that is being ordered from Posti for the shipment. One would typically agree with Posti beforehand on which services you are going to be used, and then use those service codes as appropriate for the parcel.
consignment.parcels[n].additionalServiceCodes		Array	Depending on the transportation service, some (or even multiple) additional services may also be used. The codes for these additional services are listed in this array (and are not mandatory, if none are in use). Similarly to the service code, one would agree with Posti about allowed values in advance.
consignment.parcels[n].routingServiceCode		String	Routing service code of the parcel. Only applies to service code `2106` (SmartPost).
consignment.parcels[n].additionalServices		Array	Information of additional services that apply to all order rows - can also be defined separately for each row in a row level attibute; available options must be agreed separately during service implementation.
consignment.parcels[n].additionalServices.serviceCode	(X)	String	Code of additional service. List of possible values are found from here.
consignment.parcels[n].additionalServices.telephone		String	Telephone number (with country code e.g. +3580501234567) for the additional service. Only applicable for certain services, such as electronic notice of arrival.
consignment.parcels[n].additionalServices.email		String	Email address for the additional service. Only applicable for certain services, such as electronic notice of arrival.
consignment.parcels[n].additionalServices.attributes		Array	Additional service attributes i.e. CashOnDelivery.
consignment.parcels[n].additionalServices.attributes.name	(X)	String	Attribute's name. Possible values are e.g. `CashOnDelivery`, `PostiAccount`.
consignment.parcels[n].additionalServices.attributes.value	(X)	String	Attribute's text, e.g. `true`
consignment.parcels[n].deliveryOperator		String	Delivery operator, e.g. "Posti"
consignment.parcels[n].isDangerousGoods		Boolean	Does the parcel contain ADR-products i.e. dangerous goods/hazardous materials.
consignment.parcels[n].weight		Number	Weight of parcel, in kilograms
consignment.parcels[n].volume		Number	Volume of parcel, in cubic meters
consignment.parcels[n].contentDescription		String	Description of parcel's contents.
consignment.parcels[n].trackingCodes		Array	An array of Strings. Tracking codes related to the parcel, e.g. JJFI-code
consignment.parcels[n].externalTrackingCodes		Array	An array of Strings. External tracking codes related to the parcel
consignment.parcels[n].parcelId		String	Unique identifier for the parcel.
consignment.parcels[n].rows		Array	Rows if their parcels are known.
consignment.parcels[n].rows[n].itemId		String	Item's id.
consignment.parcels[n].rows[n].vatPercentage		Number	VAT percentage used in calculating gross price of the row
consignment.parcels[n].rows[n].externalWarehouseId		String	Identifier of external warehouse.
consignment.parcels[n].rows[n].backOrder		Boolean	Indicator of whether back orders are allowed or not, in case there are insufficient supplies to fulfill the ordered quantity
consignment.parcels[n].rows[n].productEANCode		String	Identifier of product in external system.
consignment.parcels[n].rows[n].productCategory		String	Product category, e.g. `Fishing/Fishing rods/Open reel fishing rods`.
consignment.parcels[n].rows[n].productDescription		String	Description of product.
consignment.parcels[n].rows[n].crossDocking		Boolean	Indicator of whether cross docking is in use for this row
consignment.parcels[n].rows[n].quantity		Number	Quantity of order row.
consignment.parcels[n].rows[n].deliveredQuantity		Number	Delivered quantity of order row.
consignment.parcels[n].rows[n].backOrderQuantity		Number	Backorder quantity of order row, reported by warehouse
consignment.parcels[n].rows[n].unitCode		String	Describes how the item is handled e.g. pc.
consignment.parcels[n].rows[n].price		Number	Price of the row.
consignment.parcels[n].rows[n].dispositionCode		String	State of the item e.g. active.
consignment.parcels[n].rows[n].serialNumbers		Array	Array of Strings. Possible serial numbers for the product .
consignment.parcels[n].rows[n].orderRowNumber		String	Row number on the sales order.
consignment.parcels[n].rows[n].productInfo		Object	Product details object. See detailed description in Products API
consignment.parcels[n].rows[n].parentRowReference		String	Reference to parent row. Can be used to indicate that the product needs to be shipped as a bundle with the parent row.
consignment.parcels[n].rows[n].productType		String	Describes product's type. Valid values can be `serviceProduct` (e.g. "installation") or `costProduct` (e.g. "delivery cost").
consignment.parcels[n].rows[n].backOrderCancelled		Boolean	Indicates whether backorders for this row have been cancelled
consignment.parcels[n].rows[n].comments		Array	Comments regarding shipment line, e.g. comments for print outs.
consignment.parcels[n].rows[n].comments.type		String	Comment's type. Allowed values are `pickingNote`, `packingNote`, `deliveryNote`, `reference` and `passThrough`.
consignment.parcels[n].rows[n].comments.value		String	Comment's text, e.g. `pick from the oldest batch`
consignment.parcels[n].rows[n].comments.name		String	Comment's name, e.g. `comment to picking note`
consignment.parcels[n].rows[n].partialDeliveryAllowed		Boolean	Specifies if item is allowed to ship separately
consignment.parcels[n].rows[n].additionalServiceCodes		Array	Depending on the transportation service, some (or even multiple) additional services may also be used. The codes for these additional services are listed in this array (and are not mandatory, if none are in use). Similarly to the service code, one would agree with Posti about allowed values in advance.
consignment.parcels[n].rows[n].routingServiceCode		String	Routing service code of the parcel. Only applies to service code `2106` (SmartPost).
consignment.parcels[n].rows[n].productUnitOfMeasure		String	The unit of measure. Mandatory with Posti WH sales orders. Maximum length: 40
consignment.parcels[n].rows[n].lotNumber		String	Requested lot to be used in order picking
consignment.parcels[n].rows[n].print		Object	Row level details used in printing
consignment.parcels[n].rows[n].print.productTariffCode		String	Tariff code of the product
consignment.parcels[n].rows[n].print.price		String	Unit price
consignment.parcels[n].rows[n].print.vatPercentage		String	VAT percentage. Mandatory if tax used
consignment.parcels[n].rows[n].print.taxValue		String	Tax value. Mandatory if tax used
consignment.parcels[n].rows[n].print.taxName		String	Tax name. Mandatory if tax used. Maximum length: 40
consignment.parcels[n].rows[n].print.customerProductId		String	Identifier of product sold to end consumer. May be needed in prints. Maximum length: 40
consignment.parcels[n].rows[n].print.invoiceReferenceNumber		String	Cash on delivery-reference number
consignment.parcels[n].rows[n].print.invoiceBIC		String	Cash on delivery-BIC number for the bank
consignment.parcels[n].rows[n].print.invoiceIBAN		String	Cash on delivery-IBAN account number
consignment.totalNumberOfParcels		Number	Total number of parcels. This only needs to be provided if parcels are part of a `Multi-Parcel Shipment (MPS)`, and are registered over multiple shipment registration operations.
consignment.rows		Array	Rows if their parcels are unknown.
consignment.rows[n].itemId		String	Item's id.
consignment.rows[n].vatPercentage		Number	VAT percentage used in calculating gross price of the row
consignment.rows[n].externalWarehouseId		String	Identifier of external warehouse.
consignment.rows[n].backOrder		Boolean	Indicator of whether back orders are allowed or not, in case there are insufficient supplies to fulfill the ordered quantity
consignment.rows[n].productEANCode		String	Identifier of product in external system.
consignment.rows[n].productCategory		String	Product category, e.g. `Fishing/Fishing rods/Open reel fishing rods`.
consignment.rows[n].productDescription		String	Description of product.
consignment.rows[n].crossDocking		Boolean	Indicator of whether cross docking is in use for this row
consignment.rows[n].quantity		Number	Quantity of order row.
consignment.rows[n].deliveredQuantity		Number	Delivered quantity of order row.
consignment.rows[n].backOrderQuantity		Number	Backorder quantity of order row, reported by warehouse
consignment.rows[n].unitCode		String	Describes how the item is handled e.g. pc.
consignment.rows[n].price		Number	Wholesale unit price of the product, VAT 0%.
consignment.rows[n].dispositionCode		String	State of the item e.g. active.
consignment.rows[n].serialNumbers		Array	Array of Strings. Possible serial numbers for the product .
consignment.rows[n].orderRowNumber		String	Row number on the sales order.
consignment.rows[n].productInfo		Object	Product details object. See detailed description in Products API
consignment.rows[n].parentRowReference		String	Reference to parent row. Can be used to indicate that the product needs to be shipped as a bundle with the parent row.
consignment.rows[n].productType		String	Describes product's type. Valid values can be `serviceProduct` (e.g. "installation") or `costProduct` (e.g. "delivery cost").
consignment.rows[n].backOrderCancelled		Boolean	Indicates whether backorders for this row have been cancelled
consignment.rows[n].comments		Array	Comments regarding shipment line, e.g. comments for print outs.
consignment.rows[n].comments.type		String	Comment's type. Allowed values are `pickingNote`, `packingNote`, `deliveryNote`, `reference` and `passThrough`.
consignment.rows[n].comments.value		String	Comment's text, e.g. `pick from the oldest batch`
consignment.rows[n].comments.name		String	Comment's name, e.g. `comment to picking note`
consignment.rows[n].partialDeliveryAllowed		Boolean	Specifies if item is allowed to ship separately
consignment.rows[n].deliveryOperator		String	Name of the delivery operator `Posti`.
consignment.rows[n].packageType		String	Type code of the packaging used. If not defined, `PC` is assumed, which stands for parcel or letter. List of possible values are found from here (Table 5a).
consignment.rows[n].serviceCode		String	Code of Posti transport service to be used for the order row. Available options must be agreed separately during service implementation. List of possible values are found from here (Table 3).
consignment.rows[n].routingServiceCode		String	Routing service code of the parcel. Only applies to service code `2106` (SmartPost).
consignment.rows[n].additionalServiceCodes		Array	Depending on the transportation service, some (or even multiple) additional services may also be used. The codes for these additional services are listed in this array (and are not mandatory, if none are in use). Similarly to the service code, one would agree with Posti about allowed values in advance.
consignment.rows[n].additionalServices		Array	Information of additional services that apply to all order rows - can also be defined separately for each row in a row level attibute; available options must be agreed separately during service implementation.
consignment.rows[n].additionalServices.serviceCode	(X)	String	Code of additional service. List of possible values are found from here.
consignment.rows[n].additionalServices.telephone		String	Telephone number (with country code e.g. +3580501234567) for the additional service. Only applicable for certain services, such as electronic notice of arrival.
consignment.rows[n].additionalServices.email		String	Email address for the additional service. Only applicable for certain services, such as electronic notice of arrival.
consignment.rows[n].additionalServices.attributes		Array	Additional service attributes i.e. CashOnDelivery.
consignment.rows[n].additionalServices.attributes.name	(X)	String	Attribute's name. Possible values are e.g. `CashOnDelivery`, `PostiAccount`.
consignment.rows[n].additionalServices.attributes.value	(X)	String	Attribute's text, e.g. `true`
consignment.rows[n].productUnitOfMeasure		String	The unit of measure. Mandatory with Posti WH sales orders. Maximum length: 40
consignment.rows[n].lotNumber		String	Requested lot to be used in order picking
consignment.rows[n].print		Object	Row level details used in printing
consignment.rows[n].print.productTariffCode		String	Tariff code of the product
consignment.rows[n].print.price		String	Unit price
consignment.rows[n].print.vatPercentage		String	VAT percentage. Mandatory if tax used
consignment.rows[n].print.taxValue		String	Tax value. Mandatory if tax used
consignment.rows[n].print.taxName		String	Tax name. Mandatory if tax used. Maximum length: 40
consignment.rows[n].print.customerProductId		String	Identifier of product sold to end consumer. May be needed in prints. Maximum length: 40
consignment.rows[n].print.invoiceReferenceNumber		String	Cash on delivery-reference number
consignment.rows[n].print.invoiceBIC		String	Cash on delivery-BIC number for the bank
consignment.rows[n].print.invoiceIBAN		String	Cash on delivery-IBAN account number
consignment.rows[n].weight		Number	Weight in kilograms
consignment.rows[n].volume		Number	Volume in cubic meters
consignment.statuses		Array	Array containing status history of the shipment.
consignment.statuses[n].value		String	Statuses can be found here.
consignment.statuses[n].timestamp		String	DateTime in ISO 8601 format (yyyy-MM-dd'T'HH:mm:ss.SSSZZ).
warehouseType		String	Type of warehouse from Warehouse API.
trackingCodes		Array	Tracking code(s) generated for the shipment.
requestedDeliveryDate		String	The date the customer has requested the order to be delivered, in ISO 8601 format (yyyy-MM-dd'T'HH:mm:ss.SSSZZ).
requestedShipDate		String	Date when shipment from a warehouse should happen, in ISO 8601 format (yyyy-MM-dd'T'HH:mm:ss.SSSZZ).
references		Array	Array for order references
references.name		String	Name can be PO or SO. PO = Purchase Order and SO = Sales order. Both purchase and sales order may be used with drop shipping. Purchase order identifier is used to identify an order between seller and drop ship vendor. Sales order identifier is used between a seller and consumer. This id may be printed on delivery note sent to consumer. If there are no values set in references, externalId will be used both in warehouse SO and drop shipping PO processing. If PO is set then drop ship order can only be sent to one supplier set in metadata.receiverOrganization. Otherwise Posti Glue service will process the order based on pre-defined business rules agreed with the principal. In some situations, this may need to be printed on the actual packaging. Maximum length: 100
references.value		String	PO or SO value. Maximum length: 100
metadata		Object	Metadata information of the order
metadata.sourceOrganization		String	Name of the source organization that sent the order
metadata.receiverOrganization		String	Name of the receiver organization whom the order was sent to
metadata.language		String	Language code of the order, in two-letter ISO 639-1 format, e.g. `FI`
metadata.externalUserId		String	Identifier of the user in external system (OVT code)
metadata.documentType		String	Type of the document. This should be `SalesOrder`
metadata.orderType		String	The order classification attribute. This field can be used for reporting purposes or to build conditions for modeling your business process.
metadata.warehouse		Object	Used only with Posti warehouse service. If warehouse used set WH id agreed with Posti.
metadata.warehouse.sourceOrganizationId		String	Principal's Posti WH service ID
metadata.warehouse.shipNode		String	Ship node from which the order line will be fulfilled. Required id if Posti warehouse service used. Identifies principal's warehouse and is used for message monitoring. If node id is wrong, order will be set to error status. Maximum length: 24
metadata.warehouse.billToID		String	The identifier of the bill to customer. BillToID can represent the Customer number of the customer. Maximum length: 40
metadata.warehouse.shipToId		String	The identifier of the ship to customer. ShipToID can represent the Customer number of the customer. Primary information of Principal's customer. Maximum length: 40
metadata.creationDateTime		String	Datetime of order creation, in ISO 8601 format (yyyy-MM-dd'T'HH:mm:ss.SSSZZ)

Example response

{
    "clientReference" : "003723456789",
    "consignment" : {
        "metadata" : {
            "sourceOrganization" : "1234567-8",
            "receiverOrganization" : "2345678-9"
        },
        "orderDate" : "2017-04-10T12:06:01.000+03:00",
        "comments" : [ 
            {
                "type" : "reference",
                "value" : "174644",
                "name" : "confirmation"
            }
        ],
        "reference" : "123456789",
	"vendor" : {
		"externalId" : "003712345678",
		"name" : "Webshop name",
		"streetAddress" : "Postintaival 7",
		"postalCode" : "00230",
		"postOffice" : "Helsinki",
		"country" : "FI"
	},
	"sender" : {
		"externalId" : "003723456789",
		"name" : "Name of the company that will be shown as sender in the address label",
		"streetAddress" : "Example street 123",
		"postalCode" : "00100",
		"postOffice" : "Helsinki",
		"country" : "FI"
	},
	"client" : {
		"externalId" : "123456",
		"name" : "Name of the payer",
		"streetAddress" : "Home address 123",
		"postalCode" : "90900",
		"postOffice" : "Kiiminki",
		"country" : "FI"
	},
	"recipient" : {
		"externalId" : "100060",
		"name" : "Name of the recipient",
		"streetAddress" : "Recipient address 5",
		"postalCode" : "01820",
		"postOffice" : "Klaukkala",
		"country" : "FI",
		"telephone" : "04012345678",
		"email" : "firstname.lastname@example.com"
	},
	"deliveryAddress" : {
		"name" : "Recipient firstname\nRecipient lastname\nc/o Pickup point name",
		"streetAddress" : "Pickup point address 1",
		"postalCode" : "00234",
		"postOffice" : "Helsinki",
		"country" : "FI",
		"telephone" : "04012345678",
		"email" : "firstname.lastname@example.com"
	},
        "parcels" : [ 
            {
                "serviceCode" : "2W2103",
                "additionalServiceCodes" : [],
                "trackingCodes" : [],
                "externalTrackingCodes" : [],
                "rows" : [],
                "additionalServices" : []
            }
        ],
	"rows" : [ 
		{
			"orderRowNumber" : "100",
			"externalProductId" : "unique-id-1",
			"productEANCode" : "6419835068484",
			"productDescription" : "Product name shown in delivery note",
			"externalWarehouseId" : "003723456789",
			"quantity" : 3.0,
			"volume" : 0.04,
			"productUnitOfMeasure" : "KPL",
			"print" : {
				"customerProductId" : "Webshop product-id shown in delivery note"
			},
			"deliveryOperator" : "Posti",
			"serviceCode" : "2W2103",
			"additionalServices" : [ 
				{
					"serviceCode" : "3139",
					"attributes" : [ 
						{
							"name" : "telephone",
							"value" : "04012345678"
						}, 
						{
							"name" : "email",
							"value" : "firstname.lastname@example.com"
						}
					]
				}
			],
			"routingServiceCode" : "3200"
		}
	],
	"statuses" : [ 
            {
                "value" : "Routed",
                "timestamp" : "2017-04-10T17:36:19.058+03:00"
            }
        ],
        "currency" : "EUR"
    },
    "warehouseType" : "Catalog",
    "trackingCodes" : [],
    "requestedDeliveryDate" : "2017-04-12T00:00:00.000+02:00",
    "references" : [ 
        {
            "name" : "PO",
            "value" : "111222333"
        }
    ],
    "metadata" : {
        "insertDate" : "2017-04-10T05:46:20.922Z",
        "updateDate" : "2017-04-10T05:46:20.922Z",
        "sourceOrganization" : "Webshop name",
        "receiverOrganization" : "Sending warehouse name eg. vendor",
        "language" : "FI",
        "externalUserId" : "003712345678",
        "documentType" : "PurchaseOrder"
    },
    "print" : [ 
        {
            "templateId" : "standard",
            "freeText" : []
        }
    ],
    "shipmentId" : "453fsdf3-6df6-44e1-b45a-3cf2d05fe17b"
}

Response codes

Response code	Explanation
`200 OK`	Request processed successfully.
`403 Forbidden`	Requested operation is not allowed.
`404 Not Found`	Requested resource was not found.
`500 Internal Server Error`	An error occured while processing request.

Overview

Retrieve data of multiple shipments. The query can be defined with additional parameters. If no parameters are passed, query will return all the shipments.

Query string parameters

Parameter	mandatory	type	Description
since_id	no	String	Returns shipments added after the shipment with given ID. Note that the ID here means the record's data store id which can be found in "_id" element in response JSON: `"_id" : ObjectId("5639fa52180000340056f508")`
since_date	no	String, DateTime in ISO 8601 format (yyyy-MM-dd'T'HH:mm:ss.SSSZZ)	Returns shipments added after the given date
to_date	no	String, DateTime in ISO 8601 format (yyyy-MM-dd'T'HH:mm:ss.SSSZZ)	Returns shipments added before the given date

Example request

GET
/v2/shipments/?since_id=5639fa52180000340056f508&to_date=2015-06-17T10:43:00

Response fields

Array of objects with fields similar to retrieving data of a single shipment.

Response codes

Response code	Explanation
`200 OK`	Request processed successfully.
`400 Bad Request`	Data provided in request was not valid.
`403 Forbidden`	Requested operation is not allowed.
`404 Not Found`	Requested resource was not found.
`500 Internal Server Error`	An error occured while processing request.

Overview

Updating an existing shipment

In some cases, shipment data may need some changes, after its initial registration. Modifying the shipment is usually possible, with some restrictions (for example, if the parcel is already on its way to the recipient, it is too late to make changes).

Query string parameters

none

Request fields

Same as in "Retrieve data of a single shipment" -operation.

Example request

{
    "clientReference" : "003723456789",
    "consignment" : {
        "metadata" : {
            "sourceOrganization" : "1234567-8",
            "receiverOrganization" : "2345678-9"
        },
        "orderDate" : "2017-04-10T12:06:01.000+03:00",
        "reference" : "123456789",
	"vendor" : {
		"externalId" : "003712345678",
		"name" : "Webshop name",
		"streetAddress" : "Postintaival 7",
		"postalCode" : "00230",
		"postOffice" : "Helsinki",
		"country" : "FI"
	},
	"sender" : {
		"externalId" : "003723456789",
		"name" : "Name of the company that will be shown as sender in the address label",
		"streetAddress" : "Example street 123",
		"postalCode" : "00100",
		"postOffice" : "Helsinki",
		"country" : "FI"
	},
	"client" : {
		"externalId" : "123456",
		"name" : "Name of the payer",
		"streetAddress" : "Home address 123",
		"postalCode" : "90900",
		"postOffice" : "Kiiminki",
		"country" : "FI"
	},
	"recipient" : {
		"externalId" : "555666",
		"name" : "Name of the recipient",
		"streetAddress" : "Recipient address 5",
		"postalCode" : "01820",
		"postOffice" : "Klaukkala",
		"country" : "FI",
		"telephone" : "04012345678",
		"email" : "firstname.lastname@example.com"
	},
	"deliveryAddress" : {
		"name" : "Recipient firstname\nRecipient lastname\nc/o Pickup point name",
		"streetAddress" : "Pickup point address 1",
		"postalCode" : "00234",
		"postOffice" : "Helsinki",
		"country" : "FI",
		"telephone" : "04012345678",
		"email" : "firstname.lastname@example.com"
	},
        "parcels" : [ 
            {
                "packageType" : "PC",
                "serviceCode" : "2W2103",
                "routingServiceCode" : "3200",
                "deliveryOperator" : "Posti",
                "weight" : 0.5,
                "volume" : 0.5,
                "contentDescription" : "1",
                "trackingCodes" : [ ],
                "externalTrackingCodes" : [],
                "parcelId" : "123",
                "rows" : [ 
                    {
                        "itemId" : "unique-id-1",
                        "externalWarehouseId" : "003723456789",
                        "productEANCode" : "6419835068484",
                        "productDescription" : "Product name shown in delivery note",
                        "quantity" : 3.0,
                        "deliveredQuantity" : 3.0,
                        "unitCode" : "KPL",
                        "orderRowNumber" : "100",
                        "additionalServices" : [ 
                            {
                                "serviceCode" : "3139",
				"attributes" : [ 
					{
						"name" : "telephone",
						"value" : "04012345678"
					}, 
					{
						"name" : "email",
						"value" : "firstname.lastname@example.com"
					}
				]
                            }
                        ],
                        "productUnitOfMeasure" : "KPL",
                        "print" : {
                            "customerProductId" : "Webshop product-id shown in delivery note"
                        },
                        "deliveryOperator" : "Posti",
                        "routingServiceCode" : "3200"
                    }
                ],
                "additionalServices" : [ 
                    {
                        "serviceCode" : "3139",
                        "attributes" : [ 
                            {
                                "name" : "telephone",
                                "value" : "04012345678"
                            }, 
                            {
                                "name" : "email",
                                "value" : "firstname.lastname@example.com"
                            }
                        ]
                    }
                ]
            }
        ],
	"rows" : [ 
		{
			"orderRowNumber" : "100",
			"externalProductId" : "unique-id-1",
			"productEANCode" : "6419835068484",
			"productDescription" : "Product name shown in delivery note",
			"externalWarehouseId" : "003723456789",
			"quantity" : 3.0,
			"deliveredQuantity" : 3.0,
			"volume" : 0.04,
			"productUnitOfMeasure" : "KPL",
			"print" : {
				"customerProductId" : "Webshop product-id shown in delivery note"
			},
			"deliveryOperator" : "Posti",
			"serviceCode" : "2W2103",
			"additionalServices" : [ 
				{
					"serviceCode" : "3139",
					"attributes" : [ 
						{
							"name" : "telephone",
							"value" : "04012345678"
						}, 
						{
							"name" : "email",
							"value" : "firstname.lastname@example.com"
						}
					]
				}
			],
			"routingServiceCode" : "3200"
		}
	],
	"statuses" : [ 
            {
                "value" : "Routed",
                "timestamp" : "2017-04-10T17:36:19.058+03:00"
            }
        ],
        "currency" : "EUR"
    },
    "warehouseType" : "Catalog",
    "trackingCodes" : [],
    "requestedDeliveryDate" : "2017-04-12T00:00:00.000+02:00",
    "references" : [ 
        {
            "name" : "PO",
            "value" : "111222333"
        }
    ],
    "metadata" : {
        "insertDate" : "2017-04-10T05:46:20.922Z",
        "updateDate" : "2017-04-10T05:46:20.922Z",
        "sourceOrganization" : "Webshop name",
        "receiverOrganization" : "Sending warehouse name eg. vendor",
        "language" : "FI",
        "externalUserId" : "003712345678",
        "documentType" : "PurchaseOrder"
    },
    "print" : [ 
        {
            "templateId" : "standard",
            "freeText" : []
        }
    ],
    "shipmentId" : "453fsdf3-6df6-44e1-b45a-3cf2d05fe17b"
}

Response codes

Response code	Explanation
`200 OK`	Request processed successfully.
`400 Bad Request`	Data provided in request was not valid.
`403 Forbidden`	Requested operation is not allowed.
`404 Not Found`	Requested resource was not found.
`500 Internal Server Error`	An error occured while processing request.

Overview

Adding a status element to an existing shipment

Query string parameters

none

Request fields

Element	type	Description
value	String	Statuses can be found here.
timestamp	String	Date time of status change, in ISO 8601 format (yyyy-MM-dd'T'HH:mm:ss.SSSZZ).

Example request

{
	"value": "Picking",
	"timestamp": "2015-12-17T10:43:00.000+03:00"
}

JSON Schema

POST shipment status JSON schema

Response fields

Same as in retrieving data of a single shipment.

Response codes

Response code	Explanation
`200 OK`	Request processed successfully.
`400 Bad Request`	Data provided in request was not valid.
`403 Forbidden`	Requested operation is not allowed.
`404 Not Found`	Requested resource was not found.
`500 Internal Server Error`	An error occured while processing request.

Overview

Retrieve a parcel print document in PDF-format, identified by the shipment id and parcel id.

Query string parameters

Parameter	Mandatory	Type	Description
Document type	yes	String	Possible values: `deliverynote`, `parcelLabel`. For custom documents please contact Posti.
Shipment ID	yes	String	Shipment id
Parcel Id	yes	String	parcel id
size	no	String	Parcel label size. Possible values: `a5`, for other measures please contact Posti.
format	no	String	Parcel label format possible values: `normal` (148 x 210 mm), `narrow` (109 x 250 mm), `compact` (109 x 103 mm)

Request fields

none

Example request

GET
/v2/shipments/print/deliverynote/453fsdf3-6df6-44e1-b45a-3cf2d05fe17b/123

or

GET
/v2/shipments/print/parcelLabel/453fsdf3-6df6-44e1-b45a-3cf2d05fe17b/123?size=a5&format=compact

JSON Schema

Response JSON schema

Response fields

none

Example response

{
    "shipmentId": "453fsdf3-6df6-44e1-b45a-3cf2d05fe17b",
    "parcelId": "123",
    "consignmentReference": "123456789",
    "pdfUrl": "https://api.posti.fi/v2/shipments/print/pdf-document.pdf",
    "message": null
}

After this response you should start polling for pdfUrl. When the document is ready the pdfUrl will return the pdf you asked for.

Response codes

Response code	Explanation
`200 OK`	Request processed successfully.
`400 Bad Request`	Data provided in request was not valid.
`403 Forbidden`	Authentication failed
`404 Not Found`	Requested resource was not found.
`500 Internal Server Error`	An error occured while processing request.