Orders API V3

Submit and query orders

Orders API is used to place sales orders and purchase orders in the system and retrieve them. Orders can be routed to Posti’s warehouse system or external warehouse systems for picking and collecting.

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

Older V2 documentation can be found here.

API Endpoints

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

API response codes can be found here.

Sequence of order flow with rows to one supplier

Sequence of order flow with rows to different suppliers

Retailer

In the most common case Retailer will:

Create an order

GLUE orders API V3 has field externalId as unique identifier for orders. This value must be unique within retailers orders in GLUE. If you place an order without externalId value GLUE auto generates a unique order id to the externalId field. This value is returned in response message for order creation and this value must be saved on customer side to get order status later.

Most common order to use in dropshipping case is SalesOrder (PurchaseOrder usage must be agreed separately with Posti and it’s applicable to eCom warehouse service).

externalId - Own order number from online shop. If not provided with order data GLUE generates externalId. This externalId must be stored then on retailers side because getting back order status and delivery information is done using this number. externalId must be unique per retailer and must contain only characters that are supported by barcode standard Code 128. This is needed because order number is added to delivery note as a barcode.

references - if you have a purchase order (PO) number for you supplier use it in the references with PO. See API model for implementation here.

vendor - Vendor is the Webshop (retailer) who is selling the goods to end customer. Vendor address data is displayed on the delivery note document. Note that externalId field of the vendor is used to map retailer to supplier’s account in integrations (currently valid for Also and Electrolux).

sender - Sender is the party who sends out the good to end customer. Note that sender address is also where undelivered shipments are returned. Sender information is printed on the parcel label. Sender information is taken from the settings of the Retailer/Warehouse Manager if the sender information is not provided with API call.

client - Person/Company (end-customer) who has bought the goods (end-customer). This is shown only on delivery note. If deliveryOperator is “Posti”, then email OR telephone (mobile phone) is mandatory. If deliveryOperator is Unifaun, then telephone (mobile phone) is mandatory.

deliveryAddress - Address where the parcel is sent. Pickup point address.

serviceCode - Service code for the delivery. Use Posti’s service codes if you are NOT using Unifaun to create documents and EDI for the delivery. In case of deliveries through Unifaun, Unifaun service codes must be used. When placing orders to “ALSO Finland Oy” following service codes are supported: 2102, 2103 and 2104. All other service codes will be defaulted to 2103 (Delivery to Posti outlet based on home address).

Note that serviceCode is a string value, so it must be between apostrophes when sending it in the request (e.g. "2103").

Supported service codes are listed at: https://api.posti.fi/resources/SupportedServiceCodes.pdf . Note that the list does not mention the 2W prefix front of the service code (e.g. "2W2103") but it is possible for those Retailer’s who are using v2 version of the Orders API.

deliveryOperator - Posti or Unifaun. Unifaun (now called as nShift) usage must be agreed separately and it also needs API keys to be added to catalog configuration.

pickupPointId - directs the shipment to the correct service point. Values are available at Location API in the pupCode field (see more at https://developer.posti.fi). Value is deliveryOperator specific. If deliveryOperator is not Posti then pupCode value from Location API can not be used.

rows.externalProductId / rows.productEANCode - You can use either externalProductId or productEANCode for placing the order. PS! If you provide both values and one of them is not correct (not matching the GLUE data for that product) order will be rejected.

Order must contain one order row per product. When you order same product on different order rows will cause mismatches in confirmed quantities.

Do not send order rows like this (same product is on two different rows):

{
  "rows": [
    {
      "externalId": "1",
      "externalProductId": "Example-product-01",
      "externalWarehouseId": "01093579",
      "quantity": 1
    },
    {
      "externalId": "2",
      "externalProductId": "Example-product-01",
      "externalWarehouseId": "01093579",
      "quantity": 1
    }
  ]
}

Instead send order like this:

{
  "rows": [
    {
      "externalId": "1",
      "externalProductId": "Example-product-01",
      "externalWarehouseId": "01093579",
      "quantity": 2
    }
  ]
}

Order body must be sent with POST command to endpoint: {{glueApiUrl}}/ecommerce/v3/orders

Example order body

{
  "externalId": "ORDER12345",
  "vendor": {
    "name": "Name of the Seller Webshop",
    "streetAddress": "Seller address",
    "postalCode": "01530",
    "postOffice": "Vantaa",
    "country": "FI",
    "telephone": "+358440300967",
    "email": "retailer@email.com"
  },
  "client": {
    "name": "Client name",
    "streetAddress": "Client streetAddress",
    "postalCode": "00230",
    "postOffice": "Helsinki",
    "telephone": "354512222",
    "email": "client@itella.com",
    "country": "FI"
  },
  "deliveryAddress": {
    "name": "Firstname Surname c/o Pickup point name",
    "streetAddress": "Pickup point name streetAddress",
    "postalCode": "00120",
    "postOffice": "Turku",
    "country": "FI",
    "telephone": "354512222",
    "email": "client@email.com"
  },
  "serviceCode": "2103",
  "deliveryOperator": "Posti",
  "pickupPointId": "001203200",
  "totalWholeSalePrice": 123.4,
  "rows": [
    {
      "externalId": "1",
      "externalProductId": "Example-product-01",
      "externalWarehouseId": "01093579PRIIT",
      "quantity": 1
    },
    {
      "externalId": "2",
      "externalProductId": "Example-product-02",
      "externalWarehouseId": "01093579PRIIT",
      "quantity": 1
    }
  ]
}

Find full schema description here.

As a result of this order - parcel label and delivery note would look like this:

Parcel label:
Delivery note:

Glue has basic template for the delivery note. Retailer’s own logo and return instructions can be added to the delivery. Both of those shall be provided as a PNG image which is updated to the Glue by Posti’s service desk.

Poll order status and tracking information

To get back order data from GLUE use GET {{glueApiUrl}}/v3/orders/{externalId}

externalId is the value that retailer sent with and order. If externalId value was not sent with the order then use value that GLUE returned (GLUE generated externalId value is in format: XXX-XXX-XXX).

Example response for GET order for previously generated order after supplier has processed it:

Example order body

{
  "externalId": "ORDER12345",
  "clientId": "0109357-9",
  "metadata": {
    "documentType": "SalesOrder"
  },
  "orderDate": "2021-07-07T12:28:18.541+03:00",
  "vendor": {
    "name": "Name of the Seller Webshop",
    "streetAddress": "Seller address",
    "postalCode": "01530",
    "postOffice": "Vantaa",
    "country": "FI",
    "telephone": "+358440300967",
    "email": "retailer@email.com"
  },
  "sender": {
    "name": "Name of the Dispacher",
    "streetAddress": "Dispacher address",
    "postalCode": "01530",
    "postOffice": "Vantaa",
    "country": "FI",
    "telephone": "+358440300967",
    "email": "sender@email.com"
  },
  "client": {
    "name": "Client name",
    "streetAddress": "Client streetAddress",
    "postalCode": "00230",
    "postOffice": "Helsinki",
    "country": "FI",
    "telephone": "354512222",
    "email": "client@itella.com"
  },
  "deliveryAddress": {
    "name": "Firstname Surname c/o Pickup point name",
    "streetAddress": "Pickup point name streetAddress",
    "postalCode": "00120",
    "postOffice": "Turku",
    "country": "FI",
    "telephone": "354512222",
    "email": "client@email.com"
  },
  "serviceCode": "2103",
  "pickupPointId": "001203200",
  "totalWholeSalePrice": "23.4",
  "deliveryOperator": "Posti",
  "trackingCodes": [
    "JJFI60000099099003677"
  ],
  "status": {
    "value": "Delivered",
    "timestamp": "2021-07-07T12:28:37.085+03:00"
  },
  "rows": [
    {
      "externalId": "1",
      "externalProductId": "Example-product-01",
      "externalWarehouseId": "01093579PRIIT",
      "quantity": 1.0,
      "deliveredQuantity": 1.0,
      "status": {
        "value": "Delivered",
        "timestamp": "2021-07-07T12:28:37.085+03:00"
      },
      "trackingCodes": [
        "JJFI60000099099003677"
      ]
    },
    {
      "externalId": "2",
      "externalProductId": "Example-product-02",
      "productEANCode": "1234567891005",
      "externalWarehouseId": "01093579PRIIT",
      "quantity": 1.0,
      "deliveredQuantity": 1.0,
      "status": {
        "value": "Delivered",
        "timestamp": "2021-07-07T12:28:37.085+03:00"
      },
      "trackingCodes": [
        "JJFI60000099099003677"
      ]
    }
  ]
}

Find full schema description here.

status - Displays the current status of the order. Delivered means that supplier has processed the order and goods have been sent out from suppliers warehouse. PS! This Delivered status is not indicating that end customer has received the goods.

Note that rows also contain statuses. When you place order that has products from different suppliers then you need to take into account the row statuses also because different suppliers might have different processing speeds and in that case one row gets delivered but other row might still be in picking or other status. In that case order general status is Partially delivered.

Order statuses can be found here.

Tracking codes are located in 2 different places. On the order level and also on the row level. If order was sent out in multiple parcels then this allows you to see what product is in what parcel. It is recommended to use order level to get tracking code for your own system.

If order was cancelled by supplier then order will have status Delivered and order rows will have status Delivered but deliveredQuantity=0 for order rows. If non of the ordered goods where not able to send out then all order rows have deliveredQuantity=0 . If some rows where sent out then they will have the delivered value. Also there is option that order has status Cancelled.

How to use parameters to GET orders

To improve getting order statuses and delivery information GET {{glueApiUrl}}/v3/orders supports a variation of parameters that can be used.

refName - value provided with order data in references object. Should be combined with parameter refValue.

refValue - value provided with order data in references object. Should be combined with parameter refName.

status - Returns only orders that have provided status. For example polling only orders that have final “Delivered” status. Could be combined with parameter updatedFrom.

documentType - In case of warehouse solution documentType can be used to filter out sales order or purchase orders.

warehouseExternalId - Since supplier is tied to a specific warehouse then for getting orders thet where placed to one specific supplier this parameter can be used.

from - can be used to get order by orderDate value. Supported timeformat is in zulu time. Example: 2021-09-07T13:01:22.282Z. Can be combined together with parameter to get orders that order date falls between provided timestamps.

to - can be used to get order by orderDate value. Supported timeformat is in zulu time. Example: 2021-09-07T13:01:22.282Z. Can be combined together with parameter from to get orders that order date falls between provided timestamps.

updatedFrom - returns orders that have been updated after provided timestamp. Can be used together with parameter status. By asking status=Delivered and providing timestamp you can poll orders that have marked Delivered after last request. Supported timeformat is in zulu time. Example: 2021-09-07T13:01:22.282Z.

updatedTo - returns orders that have been updated before provided timestamp. Can be used together with parameter status and updatedFrom to get Delivered orders between provided timestamps. Supported timeformat is in zulu time. Example: 2021-09-07T13:01:22.282Z.