Shipments API

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.api.posti.fi
Prod HTTPS api.posti.fi

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


GET /v2/shipments/{shipmentId}

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 Status value Routed, Viewed, Picking, Packing, Shipping, Delivered.
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.

GET /v2/shipments

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.

POST /v2/shipments/{shipmentId}

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.

POST /v2/shipments/{shipmentId}/statuses

Overview

Adding a status element to an existing shipment

Query string parameters

none

Request fields

Element type Description
value String Status value Routed, Viewed, Picking, Packing, Shipping, Delivered.
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.

GET /v2/shipments/print/{documentType}/{shipmentId}/{parcelId}

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.