Shipments API V3

Confirm shipments and generate or add tracking information

Shipments API is meant for dropshipping Suppliers to receive orders from Retailers and confirm those orders. Retailer use always the Order API. If the order has products from multiple Suppliers then the Glue split the order to multiple shipments. Shipments API allows to receive your shipments, update status information, register your deliveries, retrieve tracking codes for them, and generate parcel labels for them.

Supplier will first fetch the shipments generated from Retailer's sales orders. The status information supplier adds to shipments will also be copied to the original sales order that retailer places, so the retailer will also be able to track the status of the shipments related to their orders.

Glue has following options to create address label, tracking ID and EDI for shipments:

Glue generates all required information for deliveries.
Glue uses integration with Unifaun to to generate address label, tracking and EDI for the delivery. This is used by some Retailers which have Unifaun in use. If Retailer use this option but you decide to your use your own system, then you should support service codes for deliveries used by the Unifaun.
You can use own system. You should update shipment information with tracking ID when confirming the shipment.

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

Older V2 documentation can be found here.

All new implementations shall use version 3 of the Shipments API.

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 shipment flow

In the most common case supplier will:

poll periodically for new shipments
update shipment status
confirm shipment
with tracking ID, EDI of the delivery, and delivery note from your own system
Glue provides tracking ID, address labels, and delivery note

Field name	Description
shipmentId	Unique shipment identifier generated by GLUE.
externalId	Supplier’s own reference. For example, you use it store your own order ID. The value is not shown to Retailer.
clientId	Suppliers business ID.
metadata
metadata.sourceOrganization	Retailers business ID.
metadata.insertDate	Timestamp when shipment was generated by GLUE from retailers order
metadata.updateDate	Timestamp when shipment was last updated.
metadata.documentTyepe	Defines order type. For dropshipping `SalesOrder` is used
references	Retailer’s addtional references.
references.name	Allowed values: `PO` - Retailer’s purchase order ID `SO` - Retailer’s sales order ID
references.value	Value of the reference
createdDate	Automatic timestamp when shipment was created by GLUE.
status	Current status of the shipment
status.value	Allowed values: `Created`, `Submitted`, `Viewed`, `Picking`, `Packing`, `Shipping`, `Cancelled`, `Delivered`, `Error` Status descriptions can be found here.
status.timestamp	Date and time when this status was added
consignment	Order information from Retailer
consignment.reference	Retailer’s order number. Normally this is sales order number which is available for the Retailer’s end-customer (order ID used by online shop).
consignment. contractNumber	Payers contract number for the delivery. Each retailer has their own contract number for each delivery operator. In case of Posti, this is 6 digit number starting with number 6 (e.g. “612345”)
consignment.orderDate	Order date provided by Retailer. PS! Might be different from “createdDate” value because orderDate is provided by Retailer and “createdDate” is added by system.
consignment.vendor	Retailer’s name and address. Printed on delivery note. consignment.vendor.externalId is reserved for Retailer’s ID (normally business ID) to map it with Supplier’s own ID for the retailer.
consignment.sender	Parcel deliveries: Retailer’s name and address which shall be used as sender on parcel label and EDI of the delivery information. Freight deliveries: Pick-up address for freight delivery.
consignment.client	Retailers customer who has purchased goods from online shop
consignment.recipient	Obsolete - do not use. This is available to ensure backwards compatibility with version 2 of the Orders API.
consignment.deliveryAddress	This section includes recipient's address, email and mobile phone number for the delivery. consignment.deliveryAddress.name can include new line (`\n`) to separate recipients name from pickup point name e.g. "Firstname Surname\nc/o Pickup point name". You can split those to two address fields or keep them on the same field.
consignment.deliveryOperator	Requested delivery operator. Allowed values: `Posti` - serviceCode’s are Posti’s service codes. `Unifaun` - serviceCode’s are nShifts’s service codes. This requires that you have valid API keys for nShift’s integration.
consignment.rows	Array or order rows
consignment.rows.itemId	Product Id of Supplier’s product. Glue uses this value to handle allocations for correct product.
consignment.rows.productEANCode	Product EAN code.
consignment.rows.externalWarehouseId	ID of the Retailer’s product catalog which identifies Supplier (string). Value is normally Supplier’s business ID.
consignment.rows.quantity	Quantity of ordered products
consignment.rows.productDescription	Product name for the delivery note
consignment.parcels	Array of parcels. Parcel is a object that contains products, delivery method and tracking information about the delivery. By default Glue generates one parcel and adds all ordered product rows to that parcel. Tracking codes, address labels and delivery notes are generated based on parcels. Each parcel will have it’s own labels and tracking code.
consignment.parcels.packageType	By default filled by Glue with value `PC` (Parcel). Field is informative.
consignment.parcels.serviceCode	Delivery method. Make sure with Retailer that proper delivery method is used for your shipments. This can include the delivery method for shipment in the following format: Posti’s service code e.g. “2103” for Postipaketti nShift’s (Unifaun) service code e.g. “PO2103” for Postipaketti. Supported service codes are listed at: https://api.posti.fi/resources/SupportedServiceCodes.pdf Note that the list does not mention the 2W prefix but it is possible for those Retailer’s who are using v2 version of the Orders API.
consignment.parcels.deliveryOperator	Requested delivery operator. Allowed values: `Posti` - serviceCode’s are Posti’s service codes. `Unifaun` - serviceCode’s are nShifts’s service codes.
consignment.parcels.parcelId	Parcel identifier. By default Glue generates value 1. If supplier creates multiple parcels then unique id-s must be given to additional parcels. Tracking codes, address labels and delivery notes are generated based on parcels. Each parcel will have it’s own labels and tracking code.
consignment.parcels.addtionalServices	Value added services used for the delivery. You should agree with Retailer if your products require any value added services, for example “Fragile”, “Oversized” or “LQ process”. You should add value added services even when Retailer does not send the information and product cannot be delivered without those. If product data is containing oversize and/or fragile information then GLUE automatically adds these value added services to the order. Supported value added services are listed at: https://api.posti.fi/resources/SupportedServiceCodes.pdf
consignment.parcels.pickupPointId	ID of the pick-up point (e.g. 001003200). For Posti this is the the same value with pupCode which is provided by Location API (see more at developer.posti.fi). The value includes post code combined with with routing service code (see below).
consignment.parcels.routingServiceCode	Routing service code of the pick up point. This is additional identifier of the pick-up point (e.g. 3200).

Glue provides also option to fast confirm shipments. In this case supplier don't need to provide anything more then shipment ID.

When developing the integration, please note the use of the following fields in response message (shipment API model has more fields, but these are most important from the processing of the shipment point of view):

Polling for new shipments

Shipments should be polled using endpoint:

GET {{glueApiUrl}}/ecommerce/v3/shipments?from=yyyy-mm-ddThh:mm:ssZ&status=Created,Viewed

API returns all new shipments that have been generated after provided timestamp.

This endpoint returns all shipments in an array. All following steps (confirming etc.) are done for each shipment separately.

Supplier needs to store last polling time in own system so on next polling they can use previous polling timestamp.

Whan you receive shipment you will get also requested delivery method and additional services added by Glue or retailer. Glue may add addtional services based on your product information, for eample in case where the product has “Fragile” option available. You can confirm shipment without changing them - in that case requested delivery method is confirmed for the actual delivery. You have option to change the delivery method or add additional services if needed while confirming the shipment.

PS! Note that response is paginated.

Response contains object “page”:

  "page": {
    "size": 20,
    "totalElements": 3,
    "totalPages": 1,
    "number": 0
  }

Default page size is 20. You can increase it with query parameter “size=XXX”

“totalElements” - declare that response has 3 shipments that match the search criteria.

If “totalPages” > 1 then it means that you need to make another query with same conditions and define next page number with parameter “&page=X”. Default page number is 0. In a nutshell if first response has “totalPages” > 1 then you need to loop through all the pages.

Find full schema description here.

Update shipment status

Supplier has option to update shipment status at any given time.

PATCH {{glueApiUrl}}/ecommerce/v3/shipments/{{shipmentId}}

Example payload

{
  "status": {
    "value": "Viewed"
  }
}

After status update API returns updated shipment JSON in response. Supplier MUST save this JSON to own system because the shipment contains new information and status. When supplier is not overwriting their local copy with API response there will be issue when supplier overwrites shipment stored in Glue with older data from their local copy.

Possible statuses can be found here.

Find full schema description here.

Confirming shipment

Supplier can confirm shipments in multiple ways.

Glue can generate tracking ID and address label for the delivery, using its' internal functions or Unifaun
Supplier can provide their own tracking ID while confirming the shipment

In both previous cases there is also option to split shipment into multiple parcels. By default Glue generates one parcel for the shipment and places all ordered products there.

Supplier can add additional parcel to shipment and rearrange products between parcels.

If delivery is provided directly by Posti (not using Posti through Unifaun) and all ordered amounts are delivered then its possible to use “fast confirm” endpoint. In that case Glue will generate tracking information and address labels + deliveredQuantities will match ordered quantities and status of the shipment is set to Delivered.

Confirming shipment and using Glue to generate tracking information and address labels

If supplier wants to use Glue generated tracking information and parcel labels then confirmation message for one parcel shipment looks as follows:

PATCH {{glueApiUrl}}/ecommerce/v3/shipments/{{shipmentId}}

Example payload

{
  "status": {
    "value": "Delivered"
  },
  "consignment": {
    "parcels": [
      {   "parcelId": "1",
        "packageType": "PC",
        "ready":true,
        "rows": [
          {
            "externalWarehouseId": "01093579",
            "itemId": "0109357-9-5002",
            "deliveredQuantity":1,
            "quantity": 1.0
          }
        ]
      }
    ]
  }
}

This payload confirms that ordered row with "0109357-9-5002" was delivered with the same amount that was ordered.

In response you can get the the tracking codes Glue generated from trackingCodes array. If there is more then one parcel then it will contain tracking codes for all parcels.

Parcel address label, delivery note and tracking code can be read from the corresponding parcel.

If you need to change the delivery method then include “serviceCode” and “deliveryOperator” values in the confirmation json.

Response

{
  "shipmentId": "PC4-MNQ-2S6-1",
  "clientId": "0109357-9",
  "metadata": {
    "sourceOrganization": "0109357-9",
    "insertDate": "2021-10-22T14:36:42.763+03:00",
    "documentType": "SalesOrder"
  },
  "status": {
    "value": "Delivered",
    "timestamp": "2021-10-22T14:41:51.586+03:00"
  },
  "references": [
    {
      "name": "SO",
      "value": "SO123"
    }
  ],
  "createdDate": "2021-10-22T14:36:42.763+03:00",
  "warehouseType": "Catalog",
  "trackingCodes": [
    "JJFI60000099099003809"
  ],
  "consignment": {
    "reference": "PC4-MNQ-2S6",
    "contractNumber": "600000",
    "orderDate": "2021-10-22T14:36:42.331+03:00",
    "vendor": {
      "name": "vendor name",
      "streetAddress": "vendor address",
      "postalCode": "01530",
      "postOffice": "VANTAA",
      "country": "FI",
      "telephone": "+37122222222",
      "email": "vendor@posti.com"
    },
    "sender": {
      "name": "sender name",
      "streetAddress": "sender address",
      "postalCode": "01530",
      "postOffice": "VANTAA",
      "country": "EE",
      "telephone": "+37133333333",
      "email": "sender@posti.com"
    },
    "client": {
      "name": "client Name",
      "streetAddress": "client Street 1",
      "postalCode": "00230",
      "postOffice": "HELSINKI",
      "country": "FI",
      "telephone": "+3714444444",
      "email": "client@posti.com"
    },
    "recipient": {
      "name": "client Name",
      "streetAddress": "client Street 1",
      "postalCode": "00230",
      "postOffice": "HELSINKI",
      "country": "FI",
      "telephone": "+3714444444",
      "email": "client@posti.com"
    },
    "deliveryAddress": {
      "name": "client Name",
      "streetAddress": "client Street 1",
      "postalCode": "00230",
      "postOffice": "HELSINKI",
      "country": "FI",
      "telephone": "+3714444444",
      "email": "client@posti.com"
    },
    "deliveryOperator": "Posti",
    "deliveryDateTime": "2021-10-22T14:41:51.586+03:00",
    "parcels": [
      {
        "reference": "JJFI60000099099003809",
        "packageType": "PC",
        "serviceCode": "2103",
        "pickupPointId": "002303201",
        "routingServiceCode": "3201",
        "deliveryOperator": "Posti",
        "parcelId": "1",
        "additionalServices": [
          {
            "serviceCode": "3104"
          }
        ],
        "trackingCodes": [
          "JJFI60000099099003809"
        ],
        "rows": [
          {
            "productEANCode": "PRODUCT-1-EAN",
            "externalWarehouseId": "01093579",
            "itemId": "0109357-9-5002",
            "quantity": 1.0,
            "deliveredQuantity": 1.0
          }
        ],
        "ready": true,
        "documents": {
          "label": {
            "url": "https://glue.helium.posti.com/documents/63373070a7d89cf1961dbea449947ffd5751aa1edb9331ecace8e2ee84f5d1969fa39398046141e9f90865516cd64495be803473575122be63079a6b4e4320e466a92bde3a04e452af041a8b645a0d8edacfae528ce2d040b459fd73709ece70"
          },
          "note": {
            "url": "https://glue.helium.posti.com/documents/36f4fd648be538083c5cda2fcf862d25d83b00c382c624258b2faf31d4d7cc32a4bca05c36487b73b4e06fdf0340f6ff40c64e361f4387839c4a7bb8ebc4a22cd1ce5d1a9752163bd76db03ad4be8c67"
          }
        }
      }
    ],
    "rows": [
      {
        "productEANCode": "PRODUCT-1-EAN",
        "externalWarehouseId": "01093579",
        "itemId": "0109357-9-5002",
        "quantity": 1.0,
        "deliveredQuantity": 1.0
      }
    ]
  }
}

Confirming shipment with tracking information from external system

If supplier use own or third party system to generate tracking code(s) then these values can be provided inside “trackingCodes” array.

Note that response is not containing document “label”. This is because you have provided external tracking code(s) and GLUE does not generate address label. Only delivery note is generated.

PATCH {{glueApiUrl}}/ecommerce/v3/shipments/{{shipmentId}}

Example payload

{
  "status": {
    "value": "Delivered"
  },
  "consignment": {
    "parcels": [
      {   "parcelId": "1",
        "packageType": "PC",
        "ready":true,
        "trackingCodes": [
          "EXTERNALLY GENERATED TRACKING CODE"
        ],
        "rows": [
          {
            "externalWarehouseId": "01093579",
            "itemId": "0109357-9-5002",
            "deliveredQuantity":1,
            "quantity": 1.0
          }
        ]
      }
    ]
  }
}

Divide shipment into multiple parcels and confirming them

If there is a need to split shipment into multiple parcels (to big object etc.) then this can be done using same PATCH endpoint.

What is important is that by adding new parcel object you need also provide following values to new parcel:

unique “parcelId” value inside same shipment
"packageType" - You can use “PC” as default value
“serviceCode” - depending on the service you use to deliver the parcel
"pickupPointId" - you can use values from Parcel 1 that GLUE generated
“routingServiceCode” - you can use values from Parcel 1 that GLUE generated
additionalServices - if they are needed you can use values from Parcel 1 that GLUE generated

In this example parcelId:1 was generated by GLUE and now parcel 2 was added by user.

PATCH {{glueApiUrl}}/ecommerce/v3/shipments/{{shipmentId}}

Example payload

{
  "status": {
    "value": "Delivered"
  },
  "consignment": {
    "parcels": [
      {
        "parcelId": "1",
        "packageType": "PC",
        "ready": true,
        "rows": [
          {
            "externalWarehouseId": "01093579",
            "itemId": "0109357-9-5002",
            "deliveredQuantity": 2,
            "quantity": 5.0
          }
        ]
      },
      {
        "parcelId": "2",
        "packageType": "PC",
        "serviceCode": "2103",
        "pickupPointId": "002303200",
        "routingServiceCode": "3200",
        "ready": true,
        "rows": [
          {
            "externalWarehouseId": "01093579",
            "itemId": "0109357-9-5002",
            "deliveredQuantity": 3,
            "quantity": 5.0
          }
        ]
      }
    ]
  }
}

Response

{
  "shipmentId": "PC7-ZZX-N5G-1",
  "clientId": "0109357-9",
  "metadata": {
    "sourceOrganization": "1531864-4",
    "insertDate": "2021-11-30T14:21:26.508+02:00",
    "updateDate": "2021-11-30T12:22:34.474+00:00",
    "documentType": "SalesOrder"
  },
  "status": {
    "value": "Delivered",
    "timestamp": "2021-11-30T14:22:33.641+02:00"
  },
  "references": [
    {
      "name": "SO",
      "value": "SO123"
    }
  ],
  "createdDate": "2021-11-30T14:21:26.508+02:00",
  "warehouseType": "Catalog",
  "trackingCodes": [
    "JJFI60000000000002723",
    "JJFI60000000000002724"
  ],
  "consignment": {
    "reference": "PC7-ZZX-N5G",
    "contractNumber": "600000",
    "orderDate": "2021-11-30T14:21:25.922+02:00",
    "vendor": {
      "name": "Vendor name",
      "streetAddress": "Vendor streetAddress",
      "postalCode": "01530",
      "postOffice": "Vantaa",
      "country": "FI",
      "telephone": "+37122222222",
      "email": "vendor@posti.com"
    },
    "sender": {
      "name": "Sender name",
      "streetAddress": "Sender streetAddress",
      "postalCode": "01530",
      "postOffice": "Vantaa",
      "country": "FI",
      "telephone": "+37133333333",
      "email": "sender@posti.com"
    },
    "client": {
      "name": "client name",
      "streetAddress": "client streetAddress",
      "postalCode": "00230",
      "postOffice": "HELSINKI",
      "country": "FI",
      "telephone": "+3714444444",
      "email": "client@posti.com"
    },
    "recipient": {
      "name": "recipient name",
      "streetAddress": "recipient streetAddress",
      "postalCode": "00230",
      "postOffice": "HELSINKI",
      "country": "FI",
      "telephone": "+3714444444",
      "email": "recipient@posti.com"
    },
    "deliveryAddress": {
      "name": "delAddress name c/o Pickup point name",
      "streetAddress": "deliveryAddress streetAddress",
      "postalCode": "00230",
      "postOffice": "HELSINKI",
      "country": "FI",
      "telephone": "+3714444444",
      "email": "delivery@posti.com"
    },
    "deliveryOperator": "Posti",
    "deliveryDateTime": "2021-11-30T14:22:33.641+02:00",
    "parcels": [
      {
        "reference": "JJFI60000000000002723",
        "packageType": "PC",
        "serviceCode": "2103",
        "pickupPointId": "002303200",
        "routingServiceCode": "3200",
        "deliveryOperator": "Posti",
        "weight": 1.0,
        "parcelId": "1",
        "additionalServices": [
          {
            "serviceCode": "3139",
            "telephone": "+3714444444",
            "email": "delivery@posti.com",
            "attributes": []
          }
        ],
        "trackingCodes": [
          "JJFI60000000000002723"
        ],
        "rows": [
          {
            "productUnitOfMeasure": "KPL",
            "productDescription": "productDescription to deliverynote",
            "externalWarehouseId": "153-010-PRIIT-DS",
            "itemId": "0109357-9-5002",
            "weight": 1.0,
            "quantity": 5.0,
            "deliveredQuantity": 2
          }
        ],
        "ready": true,
        "documents": {
          "label": {
            "url": "https://glue.helium.posti.com/documents/d411b3c55a59176ca54595ca3e8e03d43fff1b83491a10481b7c07a76a6b8dada02e4497b3061d6a8921502c3040e18ee646b341a78766a24f4171d2fa6070283f8d3a572fe5d27c96dc20569b670383539c652657482b6b89174ef6413a7acd"
          },
          "note": {
            "url": "https://glue.helium.posti.com/documents/5d557f4b64cd153b9983011c921d1b2f02dafb0b660a0d0670565b868d8854b4223d21172a8fac50710fc6305b3ae0d2be6e38df5cb77b7400dfa4e1d800d7e1a2aac33688fa1487d6f86de3ef4e125d"
          }
        }
      },
      {
        "reference": "JJFI60000000000002724",
        "packageType": "PC",
        "serviceCode": "2103",
        "pickupPointId": "002303200",
        "routingServiceCode": "3200",
        "parcelId": "2",
        "trackingCodes": [
          "JJFI60000000000002724"
        ],
        "rows": [
          {
            "externalWarehouseId": "153-010-PRIIT-DS",
            "itemId": "0109357-9-5002",
            "quantity": 5.0,
            "deliveredQuantity": 3
          }
        ],
        "ready": true,
        "documents": {
          "label": {
            "url": "https://glue.helium.posti.com/documents/4080877a8e3217f4e2458fe62ce13753d3be21bf06f96cc76cd7e34c3c8599db95c7571d83aa736fab742d945faebb4fb57af550967d97ee32ae0029b5ecb392a3ca5fe8c98668fdc551d62c325999abacaed32eb51d425fa1750736da380539"
          },
          "note": {
            "url": "https://glue.helium.posti.com/documents/1f2d0cb5b76ebed85fe6c0a19da8fd8b53819d0a30f55c377a4a48ba3b0026f3e495cd110afd9b5f5b74f4fa7d80a87c8347d6bddea1bde94308050698df0f5fdcee48da60d999a2f12eff428adaeb46"
          }
        }
      }
    ],
    "rows": [
      {
        "productUnitOfMeasure": "KPL",
        "productDescription": "productDescription to deliverynote",
        "externalWarehouseId": "153-010-PRIIT-DS",
        "itemId": "0109357-9-5002",
        "weight": 1.0,
        "quantity": 5.0,
        "deliveredQuantity": 5
      }
    ]
  }
}

As seen from the response for both parcels tracking codes and address labels where created.

Confirming shipment with no changes (fast confirm)

GLUE provides option to confirm shipment with no changes. This means that all products and ordered quantities are supposed to be delivered.

This case supplier don't need to provide any data in message body when confirming the shipment.

Only call that is needed is:

POST {{glueApiUrl}}/ecommerce/v3/shipments/{{shipmentId}}/delivered

In this case shipment is marked as “Delivered”, address labels are created and deliveredQuantity=ordered quantity.

Response is similar to previous confirmation. Full shipment json with tracking information is returned.

Confirming shipment with partial delivery

If you cant deliver all ordered products then you still need to include them in confirmation message but deliveredQuantity value must be set to 0. This indicates to retailer that this product was not shipped.

Canceling shipment

For total cancellation you can just update shipment status to “Cancelled”.

PATCH {{glueApiUrl}}/ecommerce/v3/shipments/{{shipmentId}}

Example payload

{
  "status": {
    "value": "Cancelled",
  }
}