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.


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

ParameterMandatoryTypeDescription
with_product_detailsnoStringValue '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

ElementTypeDescription
shipmentIdStringUnique shipment identifier.
clientReferenceStringWarehouse's order id.
consignment.documentIdStringUnique identifier of the document in supplier's system.
consignment.metadataObjectMeta data of the shipment.
consignment.metadata.sourceOrganizationStringBusiness ID of the retailer.
consignment.metadata.receiverOrganizationStringBusiness ID of the supplier.
consignment.metadata.creationDateTimeStringDateTime of creation, in ISO 8601 format (yyyy-MM-dd'T'HH:mm:ss.SSSZZ).
consignment.orderDateStringRequested delivery date for the order. DateTime in ISO 8601 format (yyyy-MM-dd'T'HH:mm:ss.SSSZZ).
consignment.deliveryDateTimeStringActual delivery date for the order. DateTime in ISO 8601 format (yyyy-MM-dd'T'HH:mm:ss.SSSZZ).
consignment.commentsArrayNotes about the shipment e.g. comments.
consignment.comments[n].typeStringNote's type. Allowed values are "reference" and "passThrough".
consignment.comments[n].valueStringNote's text.
consignment.comments[n].nameStringNote's name. e.g. "senderReference2"
consignment.referenceStringReference code for the consignment from the registrant's system. Typically an order number.
consignment.senderObjectSender of the shipment.
consignment.sender.externalIdStringIdentifier of the sender in an external system.
consignment.sender.nameStringName of the sender. May contain one linebreak (\n).
consignment.sender.streetAddressStringStreet address of the sender. May contain one linebreak (\n).
consignment.sender.postalCodeStringPostal code of the sender
consignment.sender.postOfficeStringPost office of the sender
consignment.sender.countryStringCountry of the sender
consignment.sender.telephoneStringTelephone number of the sender
consignment.sender.emailStringEmail address of the sender
consignment.vendorObjectVendor of the shipment.
consignment.vendor.externalIdStringIdentifier of the vendor in an external system.
consignment.vendor.nameStringName of the vendor. May contain one linebreak (\n).
consignment.vendor.streetAddressStringStreet address of the vendor. May contain one linebreak (\n).
consignment.vendor.postalCodeStringPostal code of the vendor
consignment.vendor.postOfficeStringPost office of the vendor
consignment.vendor.countryStringCountry of the vendor
consignment.vendor.telephoneStringTelephone number of the vendor
consignment.vendor.emailStringEmail address of the vendor
consignment.clientXObjectClient information.
consignment.client.externalIdStringIdentifier of the client in external system e.g. customer number
consignment.client.nameXStringName of the client. May contain one linebreak (\n).
consignment.client.streetAddressXStringStreet address of the client. May contain up to two linebreaks (\n).
consignment.client.postalCodeXStringPostal code of the client
consignment.client.postOfficeXStringPost office of the client
consignment.client.countryXString2-letter country code of client as defined in ISO 3166-1 alpha-2, e.g. FI
consignment.client.telephoneStringPhone number of the client with country code e.g. +358501234567
consignment.client.emailStringEmail of the client
consignment.recipientObjectRecipient of the shipment
consignment.recipient.externalIdStringIdentifier of the recipient in an external system.
consignment.recipient.nameStringName of the recipient. May contain one linebreak (\n).
consignment.recipient.streetAddressStringStreet address of the recipient. May contain one linebreak (\n).
consignment.recipient.postalCodeStringPostal code of the recipient
consignment.recipient.postOfficeStringPost office of the recipient
consignment.recipient.countryStringCountry of the recipient
consignment.recipient.telephoneStringTelephone number of the recipient
consignment.recipient.emailStringEmail address of the recipient
consignment.deliveryAddressObjectAdditional delivery address information, such as Smartpost
consignment.deliveryAddress.name(X)StringName on the additional delivery address. May contain one linebreak (\n).
consignment.deliveryAddress.streetAddress(X)StringStreet address of the additional delivery address. May contain up to two linebreaks (\n).
consignment.deliveryAddress.postalCode(X)StringPostal code of the additional delivery address
consignment.deliveryAddress.postOffice(X)StringPost office of the additional delivery address
consignment.deliveryAddress.country(X)String2-letter country code of the additional delivery address as defined in ISO 3166-1 alpha-2, e.g. FI
consignment.freightTermCodeStringDescribes how the freight cost for a shipment of goods should be billed.
consignment.labelNotesStringAn additional informative text to be printed on the parcel label. This is optional.
consignment.paymentTermStringPayment term for the order, e.g. "Cash"
consignment.totalWholeSalePriceNumberTotal wholesale price of the order.
consignment.parcelsArrayParcel(s) of the shipment. This can also mean cargo shipments.
consignment.parcels[n].referenceStringReference code for the specific parcel from registrant's system. Optional.
consignment.parcels[n].packageTypeStringType of package. PC means normal parcel or letter.
consignment.parcels[n].serviceCodeStringThis 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].additionalServiceCodesArrayDepending 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].routingServiceCodeStringRouting service code of the parcel. Only applies to service code 2106 (SmartPost).
consignment.parcels[n].deliveryOperatorStringDelivery operator, e.g. "Posti"
consignment.parcels[n].isDangerousGoodsBooleanDoes the parcel contain ADR-products i.e. dangerous goods/hazardous materials.
consignment.parcels[n].weightNumberWeight of parcel, in kilograms
consignment.parcels[n].volumeNumberVolume of parcel, in cubic meters
consignment.parcels[n].contentDescriptionStringDescription of parcel's contents.
consignment.parcels[n].trackingCodesArrayAn array of Strings. Tracking codes related to the parcel, e.g. JJFI-code
consignment.parcels[n].externalTrackingCodesArrayAn array of Strings. External tracking codes related to the parcel
consignment.parcels[n].parcelIdStringUnique identifier for the parcel.
consignment.parcels[n].rowsArrayRows if their parcels are known.
consignment.parcels[n].rows[n].itemIdStringItem's id.
consignment.parcels[n].rows[n].vatPercentageNumberVAT percentage used in calculating gross price of the row
consignment.parcels[n].rows[n].externalWarehouseIdStringIdentifier of external warehouse.
consignment.parcels[n].rows[n].backOrderBooleanIndicator of whether back orders are allowed or not, in case there are insufficient supplies to fulfill the ordered quantity
consignment.parcels[n].rows[n].productEANCodeStringIdentifier of product in external system.
consignment.parcels[n].rows[n].productCategoryStringProduct category, e.g. Fishing/Fishing rods/Open reel fishing rods.
consignment.parcels[n].rows[n].productDescriptionStringDescription of product.
consignment.parcels[n].rows[n].crossDockingBooleanIndicator of whether cross docking is in use for this row
consignment.parcels[n].rows[n].quantityNumberQuantity of order row.
consignment.parcels[n].rows[n].deliveredQuantityNumberDelivered quantity of order row.
consignment.parcels[n].rows[n].backOrderQuantityNumberBackorder quantity of order row, reported by warehouse
consignment.parcels[n].rows[n].unitCodeStringDescribes how the item is handled e.g. pc.
consignment.parcels[n].rows[n].priceNumberPrice of the row.
consignment.parcels[n].rows[n].dispositionCodeStringState of the item e.g. active.
consignment.parcels[n].rows[n].serialNumbersArrayArray of Strings. Possible serial numbers for the product .
consignment.parcels[n].rows[n].orderRowNumberStringRow number on the sales order.
consignment.parcels[n].rows[n].productInfoObjectProduct details object. See detailed description in Products API
consignment.parcels[n].rows[n].parentRowReferenceStringReference 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].productTypeStringDescribes product's type. Valid values can be serviceProduct (e.g. "installation") or costProduct (e.g. "delivery cost").
consignment.parcels[n].rows[n].backOrderCancelledBooleanIndicates whether backorders for this row have been cancelled
consignment.parcels[n].rows[n].commentsArrayComments regarding shipment line, e.g. comments for print outs.
consignment.parcels[n].rows[n].comments.typeStringComment's type. Allowed values are pickingNote, packingNote, deliveryNote, reference and passThrough.
consignment.parcels[n].rows[n].comments.valueStringComment's text, e.g. pick from the oldest batch
consignment.parcels[n].rows[n].comments.nameStringComment's name, e.g. comment to picking note
consignment.parcels[n].rows[n].partialDeliveryAllowedBooleanSpecifies if item is allowed to ship separately
consignment.parcels[n].rows[n].additionalServiceCodesArrayDepending 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].productUnitOfMeasureStringThe unit of measure. Mandatory with Posti WH sales orders. Maximum length: 40
consignment.parcels[n].rows[n].lotNumberStringRequested lot to be used in order picking
consignment.parcels[n].rows[n].printObjectRow level details used in printing
consignment.parcels[n].rows[n].print.productTariffCodeStringTariff code of the product
consignment.parcels[n].rows[n].print.priceStringUnit price
consignment.parcels[n].rows[n].print.vatPercentageStringVAT percentage. Mandatory if tax used
consignment.parcels[n].rows[n].print.taxValueStringTax value. Mandatory if tax used
consignment.parcels[n].rows[n].print.taxNameStringTax name. Mandatory if tax used. Maximum length: 40
consignment.parcels[n].rows[n].print.customerProductIdStringIdentifier of product sold to end consumer. May be needed in prints. Maximum length: 40
consignment.parcels[n].rows[n].print.invoiceReferenceNumberStringCash on delivery-reference number
consignment.parcels[n].rows[n].print.invoiceBICStringCash on delivery-BIC number for the bank
consignment.parcels[n].rows[n].print.invoiceIBANStringCash on delivery-IBAN account number
consignment.totalNumberOfParcelsNumberTotal 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.rowsArrayRows if their parcels are unknown.
consignment.rows[n].itemIdStringItem's id.
consignment.rows[n].vatPercentageNumberVAT percentage used in calculating gross price of the row
consignment.rows[n].externalWarehouseIdStringIdentifier of external warehouse.
consignment.rows[n].backOrderBooleanIndicator of whether back orders are allowed or not, in case there are insufficient supplies to fulfill the ordered quantity
consignment.rows[n].productEANCodeStringIdentifier of product in external system.
consignment.rows[n].productDescriptionStringDescription of product.
consignment.rows[n].crossDockingBooleanIndicator of whether cross docking is in use for this row
consignment.rows[n].quantityNumberQuantity of order row.
consignment.rows[n].deliveredQuantityNumberDelivered quantity of order row.
consignment.rows[n].backOrderQuantityNumberBackorder quantity of order row, reported by warehouse
consignment.rows[n].unitCodeStringDescribes how the item is handled e.g. pc.
consignment.rows[n].priceNumberWholesale unit price of the product, VAT 0%.
consignment.rows[n].dispositionCodeStringState of the item e.g. active.
consignment.rows[n].serialNumbersArrayArray of Strings. Possible serial numbers for the product .
consignment.rows[n].orderRowNumberStringRow number on the sales order.
consignment.rows[n].productInfoObjectProduct details object. See detailed description in Products API
consignment.rows[n].parentRowReferenceStringReference 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].productTypeStringDescribes product's type. Valid values can be serviceProduct (e.g. "installation") or costProduct (e.g. "delivery cost").
consignment.rows[n].backOrderCancelledBooleanIndicates whether backorders for this row have been cancelled
consignment.rows[n].commentsArrayComments regarding shipment line, e.g. comments for print outs.
consignment.rows[n].comments.typeStringComment's type. Allowed values are pickingNote, packingNote, deliveryNote, reference and passThrough.
consignment.rows[n].comments.valueStringComment's text, e.g. pick from the oldest batch
consignment.rows[n].comments.nameStringComment's name, e.g. comment to picking note
consignment.rows[n].partialDeliveryAllowedBooleanSpecifies if item is allowed to ship separately
consignment.rows[n].deliveryOperatorStringName of the delivery operator Posti.
rows.packageTypeStringType 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].serviceCodeStringCode 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].additionalServiceCodesArrayDepending 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.attributesArrayAdditional service attributes i.e. CashOnDelivery.
consignment.rows[n].additionalServices.attributes.name(X)StringAttribute's name. Possible values are e.g. CashOnDelivery, PostiAccount.
consignment.rows[n].additionalServices.attributes.value(X)StringAttribute's text, e.g. true
consignment.rows[n].productUnitOfMeasureStringThe unit of measure. Mandatory with Posti WH sales orders. Maximum length: 40
consignment.rows[n].lotNumberStringRequested lot to be used in order picking
consignment.rows[n].printObjectRow level details used in printing
consignment.rows[n].print.productTariffCodeStringTariff code of the product
consignment.rows[n].print.priceStringUnit price
consignment.rows[n].print.vatPercentageStringVAT percentage. Mandatory if tax used
consignment.rows[n].print.taxValueStringTax value. Mandatory if tax used
consignment.rows[n].print.taxNameStringTax name. Mandatory if tax used. Maximum length: 40
consignment.rows[n].print.customerProductIdStringIdentifier of product sold to end consumer. May be needed in prints. Maximum length: 40
consignment.rows[n].print.invoiceReferenceNumberStringCash on delivery-reference number
consignment.rows[n].print.invoiceBICStringCash on delivery-BIC number for the bank
consignment.rows[n].print.invoiceIBANStringCash on delivery-IBAN account number
consignment.statusesArrayArray containing status history of the shipment.
consignment.statuses[n].valueStringStatus value e.g. Created, Picking, Packing, Shipping, Delivered.
consignment.statuses[n].timestampStringDateTime in ISO 8601 format (yyyy-MM-dd'T'HH:mm:ss.SSSZZ).
warehouseTypeStringType of warehouse from Warehouse API.
trackingCodesArrayTracking code(s) generated for the shipment.
requestedDeliveryDateStringThe date the customer has requested the order to be delivered, in ISO 8601 format (yyyy-MM-dd'T'HH:mm:ss.SSSZZ).
requestedShipDateStringDate when shipment from a warehouse should happen, in ISO 8601 format (yyyy-MM-dd'T'HH:mm:ss.SSSZZ).
referencesArrayArray for order references
references.nameStringName 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.valueStringPO or SO value. Maximum length: 100
metadataObjectMetadata information of the order
metadata.sourceOrganizationStringName of the source organization that sent the order
metadata.receiverOrganizationStringName of the receiver organization whom the order was sent to
metadata.languageStringLanguage code of the order, in two-letter ISO 639-1 format, e.g. FI
metadata.externalUserIdStringIdentifier of the user in external system (OVT code)
metadata.documentTypeStringType of the document. This should be SalesOrder
metadata.orderTypeStringThe order classification attribute. This field can be used for reporting purposes or to build conditions for modeling your business process.
metadata.warehouseObjectUsed only with Posti warehouse service. If warehouse used set WH id agreed with Posti.
metadata.warehouse.sourceOrganizationIdStringPrincipal's Posti WH service ID
metadata.warehouse.shipNodeStringShip 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.billToIDStringThe identifier of the bill to customer. BillToID can represent the Customer number of the customer. Maximum length: 40
metadata.warehouse.shipToIdStringThe 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.creationDateTimeStringDatetime 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 codeExplanation
200 OKRequest processed successfully.
403 ForbiddenRequested operation is not allowed.
404 Not FoundRequested resource was not found.
500 Internal Server ErrorAn 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

ParametermandatorytypeDescription
since_idnoStringReturns 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_datenoString, DateTime in ISO 8601 format (yyyy-MM-dd'T'HH:mm:ss.SSSZZ)Returns shipments added after the given date
to_datenoString, 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 codeExplanation
200 OKRequest processed successfully.
400 Bad RequestData provided in request was not valid.
403 ForbiddenRequested operation is not allowed.
404 Not FoundRequested resource was not found.
500 Internal Server ErrorAn 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 codeExplanation
200 OKRequest processed successfully.
400 Bad RequestData provided in request was not valid.
403 ForbiddenRequested operation is not allowed.
404 Not FoundRequested resource was not found.
500 Internal Server ErrorAn 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

ElementtypeDescription
valueStringStatus type e.g. "Picking".
timestampStringDate 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 codeExplanation
200 OKRequest processed successfully.
400 Bad RequestData provided in request was not valid.
403 ForbiddenRequested operation is not allowed.
404 Not FoundRequested resource was not found.
500 Internal Server ErrorAn 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

ParameterMandatoryTypeDescription
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

Request fields

none

Example request

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

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 codeExplanation
200 OKRequest processed successfully.
400 Bad Request Data provided in request was not valid.
403 ForbiddenAuthentication failed
404 Not FoundRequested resource was not found.
500 Internal Server Error An error occured while processing request.