Tutorial: Getting started with Store shipping

Start using Posti API for your shipping

StoreShipping example

Authentication

In order to get started with Posti services, please receive credentials for your business from Posti for the authorized access. Please refer to the Authentication API for the detailed description of the process.

Getting Started

Store shipping overview

You can integrate your system with Posti API in order to use our warehousing and shipping services. You will be able to store product information and availability in your stores and warehouses. Posti also provides functionality to receive tracking codes and print parcel labels for your shipping parcels.


Store your warehouse info

Please contact Posti to provide information about your warehouses which are going to be used for Store shipping.


Store your products

Add products to your catalog. Refer to Products API for full fields description.

POST/v1/products/multiple
{ 
    "products": [{
        "externalId": "691196000580",
        "name": "Snowboard winter AC81 2015",
        "stockBalance": {
            "warehouseBalance": [
                {
                    "externalWarehouseId": "your-first-warehouse-id",
                    "quantity": 1.0,
                },
                {     
                    "externalWarehouseId": "your-second-warehouse-id",
                    "quantity": 14.0
                }
            ]
        }    
    }]  
}


Make orders

Place an order from your webstore for the existing products by executing a PUT request to Orders API. Orders will be routed to Posti’s warehouse system or external warehouse systems for shipping. Separate order lines can be routed to different warehouses based on warehouse balance and prioritization. You can agree on warehouse prioritization and certain splitting details with Posti. In cases where your order could not be routed to any warehouse, an email will be sent to your support email address.
PUT/v1/orders
{
    "externalId": "1234567",
    "orderDate": "2014-12-17T17:00:00.000+03:00",
    "metadata": {
        "sourceOrganization": "example-organization"
    },    
    "sender": {
            "name": "John Doe",
            "streetAddress": "Example Street 123\nDoor 1",
            "postalCode": "00100",
            "postOffice": "HELSINKI",
            "country": "FI",
            "telephone": "+358123456789",
            "email": "john.doe@example.com"
    },
    "recipient": {
        "name": "Jane Doe",
        "streetAddress": "Example Street 456",
        "postalCode": "00100",
        "postOffice": "HELSINKI",
        "country": "FI",
        "telephone": "+358987654321",
        "email": "jane.doe@example.com"
    },
    "currency": "EUR",
    "totalPrice": 393.85,
    "deliveryCharges" : {
        "price": 2.90,
        "vatPercentage": 24.0
    },
    "rows": [
        {
            "externalId": "691196000580",
            "price": 390.95,
            "warehouseOrderId": "123456",
            "vatPercentage": 24.0,
            "externalWarehouseId": "my-first-warehouse-id",
            "quantity": 1.0
        }
    ]
}

Orders API will return a status code 200 to confirm that an order has been successfully placed.


Register a shipment and receive a parcel label

Once your warehouse has received a notification about the new order, they will pick and collect requested items. They will register a new shipment through Shipments API and receive a tracking code and a parcel label in response.


Response Codes

Posti API aims to return HTTP status codes for every request. If you see a code that is not listed in the table, please check the official status code meaning in specification.


Response codeExplanation
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.
500 Internal Server ErrorAn error occured while processing request.