Orders API

Submit and query orders


Orders API is used to place sales orders in the system and retrieve them. Orders can be routed to Posti’s warehouse system or external warehouse systems for picking and collecting. Separate order lines can be routed to different warehouses based on product balance and prioritisation of warehouses.

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



PUT/v2/orders

Overview

Place a new order

Query string parameters

none

Request fields

ElementmandatorytypeDescription
externalIdXStringUnique identifier of the order in the seller's (webshop) system
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
orderDateXStringCreation date and time of the order, exactly in ISO 8601 format (yyyy-MM-dd'T'HH:mm:ss.SSSZZ).
promisedDeliveryDateTimeStringPromised date and time of the order's delivery, exactly in ISO 8601 format (yyyy-MM-dd'T'HH:mm:ss.SSSZZ).
requestedDeliveryDateStringThe date the customer has requested the order to be delivered, exactly in ISO 8601 format (yyyy-MM-dd'T'HH:mm:ss.SSSZZ).
requestedShipDateStringDate when shipment from a warehouse should happen, exactly in ISO 8601 format (yyyy-MM-dd'T'HH:mm:ss.SSSZZ).
metadataObjectMetadata information of the order
metadata.sourceOrganizationXStringName of the source organization (webshop) that sent the order
metadata.receiverOrganizationXStringName of the receiver (delivery warehouse) 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 (EDI code, in Finland OVT)
metadata.documentTypeStringType of the document. This should be SalesOrder or PurchaseOrder
metadata.orderTypeStringThe order classification attribute. This field can be used for reporting purposes or to build conditions for modeling your business process. See Posti WMS documentation in case Posti warehouses are used.
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.shipNode(X)StringShip 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
vendorObjectVendor information (seller, webshop). This information will be printed on delivery note generated by Glue.
vendor.externalIdStringIdentifier of the vendor in external system (OVT code)
vendor.name(X)StringName of the vendor. May contain one linebreak (\n).
vendor.streetAddress(X)StringStreet address of the vendor. May contain up to two linebreaks (\n).
vendor.postalCode(X)StringPostal code of the vendor
vendor.postOffice(X)StringPost office of the vendor
vendor.country(X)String2-letter country code of the vendor as defined in ISO 3166-1 alpha-2, e.g. FI
vendor.telephoneStringPhone number of the vendor with country code e.g. +358501234567
vendor.emailStringEmail of the vendor
senderXObjectInformation that will be shown as sender in the address label
sender.externalIdStringIdentifier of the sender in external system (EDI code)
sender.nameXStringName of the sender. May contain one linebreak (\n).
sender.streetAddressXStringStreet address of the sender. May contain up to two linebreaks (\n).
sender.postalCodeXStringPostal code of the sender
sender.postOfficeXStringPost office of the sender
sender.countryXString2-letter country code of the sender as defined in ISO 3166-1 alpha-2, e.g. FI
sender.telephoneStringPhone number of the sender with country code e.g. +358501234567
sender.emailStringEmail of the sender
clientXObjectPayer information.
client.externalIdStringIdentifier of the payer in external system e.g. customer number
client.nameXStringName of the payer. May contain one linebreak (\n).
client.streetAddressXStringStreet address of the client. May contain up to two linebreaks (\n).
client.postalCodeXStringPostal code of the payer
client.postOfficeXStringPost office of the payer
client.countryXString2-letter country code of client as defined in ISO 3166-1 alpha-2, e.g. FI
client.telephoneStringPhone number of the payer with country code e.g. +358501234567
client.emailStringEmail of the payer
recipientObjectRecipient information. If not given, client (payer) is used as the recipient.
recipient.externalIdStringIdentifier of the recipient in external system e.g. customer number
recipient.name(X)StringName of the recipient. May contain one linebreak (\n).
recipient.streetAddress(X)StringStreet address of the recipient. May contain up to two linebreaks (\n).
recipient.postalCode(X)StringPostal code of the recipient
recipient.postOffice(X)StringPost office of the recipient
recipient.country(X)String2-letter country code of the recipient as defined in ISO 3166-1 alpha-2, e.g. FI
recipient.telephoneStringPhone number of the recipient with country code e.g. +358501234567
recipient.emailStringEmail of the recipient
deliveryAddressObjectAdditional delivery address information, such as Smartpost
deliveryAddress.name(X)StringName on the additional delivery address. May contain two linebreaks (\n). Example:
deliveryAddress.streetAddress(X)StringStreet address of the additional delivery address. May contain up to two linebreaks (\n).
deliveryAddress.postalCode(X)StringPostal code of the additional delivery address
deliveryAddress.postOffice(X)StringPost office of the additional delivery address
deliveryAddress.country(X)String2-letter country code of the additional delivery address as defined in ISO 3166-1 alpha-2, e.g. FI
currecyString3-letter currency code of order in ISO 4217 standard. If not given, EUR is assumed
paymentTerm StringPayment term
invoiceObjectInvoice information
invoice.invoiceNumber(X)StringNumber of the invoice
invoice.invoiceDate(X)StringDate of the invoice, in format YYYY-MM-DD
invoice.invoiceCurrencyStringCurrency code of the invoice in ISO 4217 standard.. If not given, EUR is assumed
invoice.totalValue(X)StringTotal gross value of the invoice, in invoice currency
serviceCodeStringCode of Posti transport service to be used for all order rows. Can also be defined separately for each row in a row level attribute. Available options must be agreed separately during service implementation. List of possible values are found from here.
deliveryTermsStringDelivery terms of order, as INCOTERMS
deliveryOperatorStringName of the delivery operator Posti, Kaukokiito, Matkahuolto. Check for additional operators from Posti.
additionalServicesArrayInformation 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.
additionalServices.serviceCode(X)StringCode of additional service. List of possible values are found from here.
additionalServices.telephoneStringTelephone number (with country code e.g. +3580501234567) for the additional service. Only applicable for certain services, such as electronic notice of arrival.
additionalServices.emailStringEmail address for the additional service. Only applicable for certain services, such as electronic notice of arrival.
additionalServices.attributesArrayAdditional service attributes i.e. CashOnDelivery.
additionalServices.attributes.name(X)StringAttribute's name. Possible values are e.g. CashOnDelivery, PostiAccount.
additionalServices.attributes.value(X)StringAttribute's text, e.g. true
routingServiceCodeStringRouting service code that applies to all order rows. Can also be defined separately for each row in a row level attribute. Available options must be agreed separately during service implementation.
commentsArrayComments regarding order, e.g. comments for print outs.
comments.type(X)StringComment's type. Allowed values are pickingNote, packingNote, deliveryNote, reference and passThrough.
comments.value(X)StringComment's text. e.g. pick from the oldest batch
comments.nameStringComment's name. e.g. comment to picking note
statusesArrayArray of order statuses. The current status of the order is determined by the order rows. The status of the order is the same as the row's with the status that is the earliest in the delivery process.
statuses.valueStringStatus value e.g. Created, Picking, Packing, Shipping, Delivered.
statuses.timestampStringDate time of the status change, in ISO 8601 format (yyyy-MM-dd'T'HH:mm:ss.SSSZZ).
statuses.trackingIdsArrayStatus' tracking ids if any. e.g. JJFI-code
postiCustomerIdStringCustomer's Posti customer id a.k.a. logistic id. Logistic id is agreed with Posti and used with Prinetti.
printArrayOrder level details used for printing
print.templateIdStringPre-defined print form id, id's from Posti
print.freeTextArrayDepending on pre-defined template functionality
print.freeText.nameStringPre-defined template
print.freeText.valueStringDynamic content with pre-defined length
print.referencesBooleanIf references array has value, those will be printed based on template functionality.
rowsXArrayOrder row information (at least 1 row must be defined).
rows.externalIdXStringIdentifier of order row in external system. Glue Supplierweb requires this to be number. Number is also recommended.
rows.externalProductIdXStringIdentifier of product in external system.
rows.productEANCodeObjectCode of product.
rows.productUnitOfMeasure(X)StringThe unit of measure. Mandatory with Posti WH sales orders. Maximum length: 40
rows.productCategoryStringProduct category, e.g. Fishing/Fishing rods/Open reel fishing rods.
rows.productDescriptionStringDescription of product.
rows.serialNoArrayRequested serial number of the item. If orderline > 1 then serial number for each unit. Valid only for Posti WH. Serial number maximum length: 40
rows.lotNumberStringRequested lot to be used in order picking
rows.printObjectRow level details used in printing
rows.print.productTariffCodeStringTariff code of the product
rows.print.priceStringUnit price, VAT 0%
rows.print.vatPercentage(X)StringVAT percentage. Mandatory if tax used
rows.print.taxValue(X)StringTax value. Mandatory if tax used
rows.print.taxName(X)StringTax name. Mandatory if tax used. Maximum length: 40
rows.print.customerProductIdStringIdentifier of product sold to end consumer. May be needed in prints. Maximum length: 40
rows.print.invoiceReferenceNumberStringCash on delivery-reference number
rows.print.invoiceBICStringCash on delivery-BIC number for the bank
rows.print.invoiceIBANStringCash on delivery-IBAN account number
rows.productTariffCodeStringTariff code of the product
rows.priceNumberWholesale unit price of the product, VAT 0%
rows.vatPercentageNumberVAT percentage used in the row
rows.externalWarehouseIdStringIdentifier of the warehouse in an external system (OVT code).
rows.backOrderBooleanIndicator of whether back orders are allowed or not, in case there are insufficient supplies to fulfill the ordered quantity
rows.mandatoryBooleanIndicator of whether the row contains a critical product without which the order cannot be delivered
rows.crossDockingBooleanIndicator of whether cross docking is in use for this row
rows.quantityXNumberQuantity of the order row
rows.weightNumberWeight of the order row in kg
rows.volumeNumberVolume of the order row in m3
rows.parentRowReferenceStringReference to parent row. Can be used to indicate that the product needs to be shipped as a bundle with the parent row.
rows.productTypeStringDescribes product's type. Valid values can be serviceProduct (e.g. "installation") or costProduct (e.g. "delivery cost").
rows.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).
rows.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.
rows.routingServiceCodeStringRouting service code that applies to the order row. Available options must be agreed separately during service implementation.
rows.additionalServicesArrayInformation of additional services that apply to the order row; available options must be agreed separately during service implementation.
rows.additionalServices.serviceCode(X)StringCode of additional service, e.g. 3139 (for SmartPost). List of possible values are found from here.
rows.additionalServices.telephoneStringTelephone number for the additional service. Only applicable for certain services, such as electronic notice of arrival.
rows.additionalServices.emailStringEmail address for the additional service. Only applicable for certain services, such as electronic notice of arrival.
rows.additionalServices.attributesArrayAdditional service attributes i.e. CashOnDelivery.
rows.additionalServices.attributes.name(X)StringAttribute's name. Possible values are e.g. CashOnDelivery, PostiAccount.
rows.additionalServices.attributes.value(X)StringAttribute's text, e.g. true
rows.commentsArrayComments regarding order line, e.g. comments for print outs.
rows.comments.type(X)StringComment's type. Allowed values are pickingNote, packingNote, deliveryNote, reference and passThrough.
rows.comments.value(X)StringComment's text, e.g. pick from the oldest batch
rows.comments.nameStringComment's name, e.g. comment to picking note
rows.partialDeliveryAllowedBooleanSpecifies if item is allowed to ship separately
rows.statusesArrayStatus of the row. Status indicates which point the row is at in the delivery process.
rows.statuses.valueStringStatus value e.g. Created, Routed, Picking, Packing, Shipping, Delivered.
rows.statuses.timestampStringDate time of the status change, in ISO 8601 format (yyyy-MM-dd'T'HH:mm:ss.SSSZZ).
rows.statuses.trackingIdsArrayStatus' tracking ids if any. e.g. JJFI-code
rows.shipmentIdsArrayShipment ids of the row. Refers to the shipments related to the order row.
rows.warehouseObjectUsed only with Posti warehouse service.
rows.warehouse.segmentTypeStringIndicates SegmentType for the order line. For a Made to Customer Order, the value is MTC. For a Dynamic Physical Kit item which is Made To Order, SegmentType is MTO. Maximum length: 10
rows.warehouse.segmentStringIndicates Segment for the order line. For a Made To Customer order, the value is defaulted to BuyerOrganizationCode. For a Made To Order Order, the value is defaulted to OrderLineKey. Maximum length: 100

Example request

{
    "externalId" : "123456789",
    "orderDate" : "2017-04-10T12:06:01.000+03: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"
    },
    "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"
    },
    "currency" : "EUR",
    "requestedDeliveryDate" : "2017-04-12T00:00:00.000+02:00",
    "print" : [ 
        {
            "templateId" : "standard",
            "freeText" : []
        }
    ],
	"deliveryOperator" : "Posti",
    "serviceCode" : "2W2103",
    "postiCustomerId" : "12345",
    "rows" : [ 
        {
            "externalId" : "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",
        }
    ]
}

            

Response codes

Response codeMeaning
200 SuccessSuccesfully completed.
400 Bad RequestData provided in request was not valid.
403 ForbiddenRequested operation is not allowed.
404 Not FoundRequested resource was not found.
409 Conflict Order with the same externalId already exist
500 Internal Server ErrorAn error occured while processing request.

GET/v2/orders/order/{orderNumber}

Overview

Retrieve a sales order

Query string parameters

None

Response fields

An instance of order. The content depends on the information sent with the order originally. Please refer to the description of placing a new order for the extensive field list. Only the differing fields are described in the table below.

ElementtypeDescription
metadata.insertDateStringDatabase record creation date and time, in ISO 8601 format (yyyy-MM-dd'T'HH:mm:ss.SSSZZ).
metadata.updateDateStringDatabase record update date and time, in ISO 8601 format (yyyy-MM-dd'T'HH:mm:ss.SSSZZ).
metadata.creationDateTimeStringDatetime of order creation, in ISO 8601 format (yyyy-MM-dd'T'HH:mm:ss.SSSZZ)
rows.deliveredQuantityNumberDelivered quantity of the order row
rows.toBeRoutedQuantityNumberQuantity still left to be routed on the order row. Used in backorder handling, should equal (rows.quantity - rows.deliveredQuantity)
rows.routedWarehousesArrayArray of warehouses to which the order row has been routed to
rows.routedWarehouses.externalWarehouseIdStringWarehouse id
rows.routedWarehouses.timestampStringDate and time when the order row was routed to given warehouse, in ISO 8601 format (yyyy-MM-dd'T'HH:mm:ss.SSSZZ).
rows.routedWarehouses.requestedQuantityNumberThe order row quantity that was routed to given warehouse
rows.lastRoutedDateTimeStringDate and time of the last time the order row was routed, in ISO 8601 format (yyyy-MM-dd'T'HH:mm:ss.SSSZZ).
rows.backOrderCancelledBooleanIndicator of whether further backorders for this row have been manually cancelled in Glue-UI

Response codes

Response codeMeaning
200Successful request.
404The order does not exist.
500Internal error occured while processing request.