Shipping

Welcome to the Montonio Shipping API developer documentation. Here, you can find instructions on how to integrate with Montonio Shipping.

API URLs

API Base URLs for the available environments are as follows:

• Production: https://shipping.montonio.com/api/v2
• Sandbox: https://sandbox-shipping.montonio.com/api/v2

Read more about the sandbox environment in the Sandbox guide.

Authentication

The Shipping API uses JWT (JSON Web Tokens) for authentication. All the endpoints require a JWT in the Authorization header as a Bearer token.

JWT must contain your Access Key and be signed with your Secret Key using HMAC SHA256 (HS256). Read more about API keys here.

The exact implementation of generating the JWT varies by programming language, and you can see some examples on the code panel. We recommend using popular community-maintained libraries for generating and verifying JWTs.

Visit jwt.io to learn more about JWTs, find libraries for your programming language, or debug and verify your JWTs.

JWT headers

Key	Required	Type	Description
alg	yes	string	Must be set to HS256
typ	yes	string	Must be set to JWT

JWT payload

Here is the minimum required payload for all requests:

Key	Required	Type	Description
accessKey	yes	string	Your Access Key obtained from the Partner System.
exp	yes	number	Expiration time of the token in Unix time. We recommend setting this to 1 hour from issuing the token.

JavaScript

/**
 * We recommend using the jsonwebtoken package to generate
 * Json Web Tokens. You can install it with npm:
 * > npm install jsonwebtoken
 * More information can be found at
 * https://www.npmjs.com/package/jsonwebtoken
 */

import jwt from 'jsonwebtoken';

const payload = {
    accessKey: 'MY_ACCESS_KEY'
};

const authHeader = jwt.sign(
    payload,
    'MY_SECRET_KEY',
    { algorithm: 'HS256', expiresIn: '1h' }
);

console.log(authHeader);
// eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhY2Nlc3NLZXkiOiJNWV9BQ0NFU1NfS0VZIiwiaWF0IjoxNjc1OTM4NjM3LCJleHAiOjE2NzU5NDIyMzd9.f-wXP8t5HGhr5XKAl3eCeWbHnY3SO9DcY5WiWo06-uQ

PHP

<?php
/**
 * We recommend using Firebase's php-jwt package to verify
 * Json Web Tokens. You can install it with composer:
 * > composer require firebase/php-jwt
 * More information can be found at
 * https://github.com/firebase/php-jwt
 */

// Should be loaded only once in the app, check composer docs for the specific framework you are using
require __DIR__ . '/vendor/autoload.php';

use \Firebase\JWT\JWT;

$payload = [
    'accessKey' => 'MY_ACCESS_KEY',
    'iat'        => time(),
    'exp'        => time() + (60 * 60)
];

$token = JWT::encode($payload, 'MY_SECRET_KEY', 'HS256');
// var_dump($token);
// eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhY2Nlc3NLZXkiOiJNWV9BQ0NFU1NfS0VZIiwiaWF0IjoxNjc2MDQ1NTg5LCJleHAiOjE2NzYwNDkxODl9.9kz7LBZZVJrJbSO_42NTTg1Wg4HEP01cqOw0IzQ0nXU

Python

'''
We recommend using the PyJWT package to generate
Json Web Tokens. You can install it with pip:
> pip3 install PyJWT datetime
More information can be found at
https://pyjwt.readthedocs.io/en/latest/
'''
import jwt
from datetime import datetime, timedelta, timezone

payload = {
    'accessKey': 'MY_ACCESS_KEY',
    'iat': datetime.now(timezone.utc),
    'exp': datetime.now(timezone.utc) + timedelta(hours=1)
}

auth_header = jwt.encode(
    payload,
    'MY_SECRET_KEY',
    algorithm='HS256'
)

print(auth_header)
# eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhY2Nlc3Nfa2V5IjoibWVyY2hhbnRfYWNjZXNzX2tleSIsImlhdCI6MTYwMzcxMTQ3NSwiZXhwIjoxNjAzNzE1MDc1fQ.UYwRQXykcIVNzIjni3icf_FBbxSXZ_m-2SsFfz3zjBs

Common API response codes

Some response codes apply to all the endpoints listed below.

Http code	Description
400	Input data validations failed. There might be some validation issues with the request body, query params, or URL parameters. Please review the request body requirements to fix the issue.
401	JWT token validation failed. Please check the authentication guide to construct a valid token.
404	Requested or related resource is not found. The entity that you are trying to retrieve does not exist.

API endpoints

Get all carriers

The endpoint allows you to fetch all carriers available through the Montonio Shipping API. It will tell you which carriers can be activated, which are already activated, and whether the carrier supports a Montonio contract.

Endpoint path

GET /carriers

Authentication

Refer to the Authentication section. Follow instructions for GET endpoints.

Headers

Key	Required	Value
Authorization	yes	Bearer [your_token]

Example request

curl -X 'GET' \
'https://shipping.montonio.com/api/v2/carriers' \
-H 'accept: application/json' \
-H 'Authorization: Bearer [your_token]'

Show / Hide Response Data

{
    "carriers": [
        {
            "id": "aa8c5e19-ab56-425a-b8b8-7564b690a080",
            "code": "smartpost",
            "name": "SmartPosti",
            "logoUrl": "https://public.montonio.com/images/carrier_logos/smartpost.svg",
            "contracts": null,
            "hasMontonioContract": true,
            "supportedContractTypes": ["DIRECT", "MONTONIO"]
        },
        {
            "id": "d292aff8-709e-4d46-9e49-be0a9670eddf",
            "code": "omniva",
            "name": "Omniva",
            "logoUrl": "https://public.montonio.com/images/carrier_logos/omniva.svg",
            "contracts": [
                {
                    "id": "8c804942-4258-4fb1-b1a3-e3ac391f303c",
                    "carrierId": "d292aff8-709e-4d46-9e49-be0a9670eddf",
                    "country": "EE",
                    "lastUsedParcelNumber": null,
                    "daysAllowedForReturns": null,
                    "isDirectContract": true,
                    "createdAt": "2024-05-28T08:00:40.404Z",
                    "returnsAllowed": false,
                    "parcelHandoverMethod": null,
                    "defaultLockerSize": null,
                    "logisticsContractNumber": null,
                    "credentials": {
                        "username": "my_username"
                    }
                }
            ],
            "hasMontonioContract": true,
            "supportedContractTypes": ["DIRECT", "MONTONIO"]
        },
        {
            "id": "cc118dac-f9e0-4163-b281-7006fddc08e7",
            "code": "dpd",
            "name": "DPD",
            "logoUrl": "https://public.montonio.com/images/carrier_logos/dpd.svg",
            "contracts": [
                {
                    "id": "b75774ef-e5d0-451b-81be-bf346ed959b1",
                    "carrierId": "cc118dac-f9e0-4163-b281-7006fddc08e7",
                    "country": "EE",
                    "lastUsedParcelNumber": null,
                    "daysAllowedForReturns": null,
                    "isDirectContract": true,
                    "createdAt": "2024-05-29T08:05:23.295Z",
                    "returnsAllowed": false,
                    "parcelHandoverMethod": null,
                    "defaultLockerSize": null,
                    "logisticsContractNumber": null,
                    "credentials": {
                        "username": "my_username"
                    }
                }
            ],
            "hasMontonioContract": true,
            "supportedContractTypes": ["DIRECT", "MONTONIO"]
        },
        {
            "id": "8c6fa25b-3ee9-46e1-afd6-570d6b4ec1fe",
            "code": "venipak",
            "name": "Venipak",
            "logoUrl": "https://public.montonio.com/images/carrier_logos/venipak.svg",
            "contracts": [
                {
                    "id": "a74349d7-d1d8-46a8-87d6-c750a6a1343b",
                    "carrierId": "8c6fa25b-3ee9-46e1-afd6-570d6b4ec1fe",
                    "country": "EE",
                    "lastUsedParcelNumber": 12350,
                    "daysAllowedForReturns": null,
                    "isDirectContract": true,
                    "createdAt": "2024-05-28T10:07:34.086Z",
                    "returnsAllowed": false,
                    "parcelHandoverMethod": null,
                    "defaultLockerSize": null,
                    "logisticsContractNumber": null,
                    "credentials": {
                        "username": "my_username"
                    }
                }
            ],
            "hasMontonioContract": false,
            "supportedContractTypes": ["DIRECT"]
        }
    ]
}

Response codes

Http code	Description
200	Represents the request has been processed successfully. It will return all store carriers.

Response fields

Key	Type	Description
carriers	array	List of carriers available through Montonio Shipping.
carriers[].id	string	Unique identifier of the carrier.
carriers[].code	string	Carrier code used in API requests.
carriers[].name	string	Display name of the carrier.
carriers[].logoUrl	string	URL to the carrier’s logo image.
carriers[].contracts	array or null	List of active contracts for this carrier, or null if no contracts are activated.
carriers[].hasMontonioContract	boolean	Whether this carrier supports Montonio contracts (required for rate calculation).
carriers[].supportedContractTypes	array	List of contract types the carrier supports: DIRECT, MONTONIO, or both.
carriers[].contracts[].id	string	Unique identifier of the contract.
carriers[].contracts[].carrierId	string	Reference to the carrier.
carriers[].contracts[].country	string	Country code for the contract (ISO 3166-2).
carriers[].contracts[].lastUsedParcelNumber	number or null	Last used parcel number for sequential numbering.
carriers[].contracts[].daysAllowedForReturns	number or null	Number of days allowed for returns.
carriers[].contracts[].isDirectContract	boolean	Whether this is a direct contract with the carrier.
carriers[].contracts[].returnsAllowed	boolean	Whether returns are enabled for this contract.
carriers[].contracts[].parcelHandoverMethod	string or null	Parcel handover method (Unisend only): COURIER, LOCKER, or null.
carriers[].contracts[].defaultLockerSize	string or null	Default locker size (Unisend only): S, M, L, XL, or null.
carriers[].contracts[].logisticsContractNumber	string or null	Logistics contract number if applicable.
carriers[].contracts[].credentials	object	Contract credentials information.
carriers[].contracts[].credentials.username	string or null	Username for direct contracts (masked for security).
carriers[].contracts[].createdAt	string	ISO 8601 timestamp of when the contract was created.

Get shipping methods for a store

The endpoint lets you fetch available carriers with shipping methods grouped by country for your store. This enables you to display the available carriers and their shipping methods by country.

Endpoint path

GET /shipping-methods

Authentication

Refer to the Authentication section. Follow instructions for GET endpoints.

Headers

Key	Required	Value
Authorization	yes	Bearer [your_token]

Example request

curl -X 'GET' \
'https://shipping.montonio.com/api/v2/shipping-methods' \
-H 'accept: application/json' \
-H 'Authorization: Bearer [your_token]'

Show / Hide Response Data

{
  "countries": [
    {
      "carriers": [
        {
          "carrierCode": "dpd",
          "shippingMethods": [
            {
              "type": "courier",
              "subtypes": [
                { "code": "standard" }
              ],
              "constraints": {
                "parcelDimensionsRequired": false
              }
            },
            {
              "type": "pickupPoint",
              "subtypes": [
                { "code": "parcelMachine" },
                { "code": "parcelShop" }
              ],
              "constraints": {
                "parcelDimensionsRequired": false
              }
            }
          ]
        },
        {
          "carrierCode": "omniva",
          "shippingMethods": [
            {
              "type": "courier",
              "subtypes": [
                { "code": "standard" }
              ],
              "constraints": {
                "parcelDimensionsRequired": false
              }
            },
            {
              "type": "pickupPoint",
              "subtypes": [
                { "code": "parcelMachine" },
                { "code": "postOffice" }
              ],
              "constraints": {
                "parcelDimensionsRequired": false
              }
            }
          ]
        }
      ],
      "countryCode": "EE"
    }
  ]
}

Response codes

Http code	Description
200	Represents the request has been processed successfully. It will return all store shipping methods.

Response fields

Each shipping method in the response includes:

Key	Type	Description
type	string	The type of shipping method. Available values: courier, pickupPoint.
subtypes	array	List of subtypes available for this shipping method.
subtypes[].code	string	Subtype identifier. For pickupPoint: parcelMachine, postOffice, parcelShop. For courier: standard, standardB2B.
constraints	object	Constraints and requirements for this shipping method.
constraints.parcelDimensionsRequired	boolean	Whether parcel dimensions (length, width, height) are required when creating shipments with this shipping method. When true, the length, width, and height fields must be provided for each parcel in the shipment request.

Note

The parcelDimensionsRequired flag varies by carrier, shipping method, and country. Always check the flag in the API response for accurate requirements when displaying shipping options and conditionally require dimension inputs in the checkout flow when the flag is true.

Get pickup points for a store

The endpoint allows you to fetch carrier-specific pickup points for your store. If you use the type query param, you can further narrow down your search results.

Note

The types of pickup points vary depending on the country and carrier. To find out all the possible options for a carrier and country, fetch the pickup points without the type query parameter and group the results by “type”.

Endpoint path

GET /shipping-methods/pickup-points

Authentication

Refer to the Authentication section. Follow instructions for GET endpoints.

Headers

Key	Required	Value
Authorization	yes	Bearer [your_token]

Query Params

Key	Type	Required	Value
carrierCode	string	yes	Use /carriers or /shipping-methods endpoint to get the list of carriers and the corresponding code for each.
countryCode	string	yes	Receiver country code. Country codes are defined by the ISO 3166-2 standard.
type	string	no	Available values: postOffice,parcelShop,parcelMachine

Example request

curl -X 'GET' \
'https://shipping.montonio.com/api/v2/shipping-methods/pickup-points?carrierCode=omniva&countryCode=EE&type=parcelMachine' \
-H 'accept: application/json' \
-H 'Authorization: Bearer [your_token]'

Show / Hide Response Data

{
  "pickupPoints": [
    {
      "id": "98b391d7-5299-447c-9ad7-6b4042ef8b2f",
      "name": "Laagri Coop Maksimarketi pakiautomaat",
      "type": "parcelMachine",
      "streetAddress": "Pärnu mnt 558a",
      "locality": "Laagri alevik",
      "postalCode": "96067",
      "carrierCode": "omniva",
      "additionalServices": [
        { "code": "cod" },
        { "code": "ageVerification" }
      ]
    },
    {
      "id": "0739f3d5-a500-4f15-8432-a03ed6f82e91",
      "name": "Laagri Veskitammi Maxima X pakiautomaat",
      "type": "parcelMachine",
      "streetAddress": "Veskitammi tn 3",
      "locality": "Laagri alevik",
      "postalCode": "96381",
      "carrierCode": "omniva",
      "additionalServices": []
    }
  ],
  "countryCode": "EE"
}

Response codes

Http code	Description
200	Return all the pickup points for the store.

Response fields

Each pickup point in the response includes:

Key	Type	Description
id	string	The unique identifier of the pickup point. Use this as the shippingMethod.id when creating a shipment.
name	string	The name of the pickup point.
type	string	The type of pickup point. Values: parcelMachine, postOffice, parcelShop.
streetAddress	string	The street address of the pickup point.
locality	string	The city or locality of the pickup point.
postalCode	string	The postal code of the pickup point.
carrierCode	string	The carrier code for this pickup point.
additionalServices	array	List of additional services available for this pickup point. Each service has a code field (cod or ageVerification).

Note

The additionalServices array indicates which additional services can be used when creating a shipment to this pickup point. Only include services in your shipment request that are listed here.

Get courier services for a store

The endpoint allows you to fetch carrier-specific courier services for your store.

Endpoint path

GET /shipping-methods/courier-services

Authentication

Refer to the Authentication section. Follow instructions for GET endpoints.

Headers

Key	Required	Value
Authorization	yes	Bearer [your_token]

Query Params

Key	Type	Required	Value
carrierCode	string	yes	Use the /carriers or /shipping-methods endpoint to get available carrier codes.
countryCode	string	yes	Receiver country code. Country codes are defined by the ISO 3166-2 standard.

Example request

curl -X 'GET' \
'https://shipping.montonio.com/api/v2/shipping-methods/courier-services?carrierCode=omniva&countryCode=EE' \
-H 'accept: application/json' \
-H 'Authorization: Bearer [your_token]'

Show / Hide Response Data

{
  "courierServices": [
    {
      "id": "0ffb9b04-3927-462a-a393-4f1e21f2ee55",
      "name": "Standard",
      "type": "standard",
      "carrierCode": "omniva",
      "additionalServices": [
        { "code": "cod" }
      ]
    }
  ],
  "countryCode": "EE"
}

Response codes

Http code	Description
200	Return all the courier services for the store.

Response fields

Each courier service in the response includes:

Key	Type	Description
id	string	The unique identifier of the courier service. Use this as the shippingMethod.id when creating a shipment.
name	string	The display name of the courier service.
type	string	The type of courier service. Values: standard, standardB2B.
carrierCode	string	The carrier code for this courier service.
additionalServices	array	List of additional services available for this courier service. Each service has a code field (cod or ageVerification).

Note

The additionalServices array indicates which additional services can be used when creating a shipment with this courier service. Only include services in your shipment request that are listed here.

Get possible shipping methods for given parcels

The endpoint allows you to fetch all shipping methods considering the parcel dimensions. This is a way to validate which shipping methods are available for a specific route, considering parcels and dimensions. For example, parcel machines have specific weight and dimension limits.

Endpoint path

POST /shipping-methods/filter-by-parcels

Authentication

Refer to the Authentication section. Follow instructions for GET endpoints.

Headers

Key	Required	Value
Authorization	yes	Bearer [your_token]

Query Params

Key	Type	Required	Value
destination	string	yes	Country codes defined by the ISO 3166-2 standard.
source	string	no	If not provided, we will use your store’s default shipping address. Country codes are defined by the ISO 3166-2 standard.

Body

Key	Type	Required	Value
parcels	array	yes	The list of parcels. Possible values for parcel dimensions. Key Type Required Value weight number yes 2. weight should be measured in kg. At the moment, only two digits are allowed after decimal. height number no 0.64. height should be measured in meters. At the moment, only two digits are allowed after decimal. width number no 0.38. the width should be measured in meters. At the moment, only two digits are allowed after decimal. length number no 0.39. length should be measured in meters. At the moment, only two digits are allowed after decimal.

Example request

curl -X 'POST' \'https://shipping.montonio.com/api/v2/shipping-methods/filter-by-parcels?destination=EE&source=EE' \
-H 'accept: application/json' \
-H 'Authorization: Bearer [your_token]' \
-H 'Content-Type: application/json' \
-d '{
      "parcels": [{
          "weight": 2,
          "length": 0.61,
          "height": 0.36,
          "width": 0.43
      }]
}'

Show / Hide Response Data

{
  "countries": [
    {
      "carriers": [
        {
          "carrierCode": "dpd",
          "shippingMethods": [
            {
              "type": "courier",
              "constraints": {
                "parcelDimensionsRequired": false
              }
            },
            {
              "type": "pickupPoint",
              "constraints": {
                "parcelDimensionsRequired": false
              }
            }
          ]
        },
        {
          "carrierCode": "omniva",
          "shippingMethods": [
            {
              "type": "courier",
              "constraints": {
                "parcelDimensionsRequired": false
              }
            },
            {
              "type": "pickupPoint",
              "constraints": {
                "parcelDimensionsRequired": false
              }
            }
          ]
        },
        {
          "carrierCode": "venipak",
          "shippingMethods": [
            {
              "type": "courier",
              "constraints": {
                "parcelDimensionsRequired": false
              }
            },
            {
              "type": "pickupPoint",
              "constraints": {
                "parcelDimensionsRequired": false
              }
            }
          ]
        }
      ],
      "countryCode": "EE"
    }
  ]
}

Response codes

Http code	Description
200	Return all store shipping methods available for parcels.

Response fields

The response structure is the same as the GET /shipping-methods endpoint. Each shipping method includes a constraints object with a parcelDimensionsRequired field. See the Response fields section above for details.

Calculate shipping rates

The endpoint allows you to calculate shipping rates for given parcels and destination. This is useful for displaying shipping costs to customers at checkout before creating a shipment.

Montonio Contract Required

This endpoint only returns rates for carriers with Montonio contracts. Carriers that only support Direct contracts will not be included in the response. To use this endpoint, ensure you have activated a Montonio contract for the carrier through the Partner System.

Endpoint path

POST /shipping-methods/rates

Authentication

Refer to the Authentication section. Follow instructions for GET endpoints.

Headers

Key	Required	Value
Authorization	yes	Bearer [your_token]

Query Params

Key	Type	Required	Value
carrierCode	string	no	Filter by carrier code.
shippingMethodType	string	no	Filter by shipping method type. Values: courier, pickupPoint.

Body

Key	Type	Required	Description
destination	string	yes	Destination country code (ISO 3166-2).
parcels	array	yes	Array of parcels, each containing an items array. Key Type Required Description items array yes Array of items in the parcel. items[].length number yes Item length. items[].width number yes Item width. items[].height number yes Item height. items[].dimensionUnit string no Dimension unit: cm (default), m, mm. items[].weight number yes Item weight. items[].weightUnit string no Weight unit: kg (default), g. items[].quantity number no Item quantity. Default: 1. Max: 1000.

Example request

curl -X 'POST' \
'https://shipping.montonio.com/api/v2/shipping-methods/rates?shippingMethodType=pickupPoint' \
-H 'accept: application/json' \
-H 'Authorization: Bearer [your_token]' \
-H 'Content-Type: application/json' \
-d '{
    "destination": "EE",
    "parcels": [
        {
            "items": [
                {
                    "length": 20,
                    "width": 15,
                    "height": 10,
                    "dimensionUnit": "cm",
                    "weight": 0.5,
                    "weightUnit": "kg",
                    "quantity": 1
                }
            ]
        }
    ]
}'

Show / Hide Response Data

{
    "calculationDetails": {
        "estimatedParcels": [
            {
                "length": 20,
                "width": 15,
                "height": 10,
                "dimensionUnit": "cm",
                "actualWeight": 0.5,
                "volumetricWeight": 0.75,
                "chargeableWeight": 0.75,
                "weightUnit": "kg",
                "bufferApplied": 0
            }
        ]
    },
    "destination": "EE",
    "carriers": [
        {
            "carrierCode": "omniva",
            "shippingMethods": [
                {
                    "type": "pickupPoint",
                    "subtypes": [
                        {
                            "code": "parcelMachine",
                            "rate": "2.50",
                            "currency": "EUR"
                        },
                        {
                            "code": "postOffice",
                            "rate": "2.50",
                            "currency": "EUR"
                        }
                    ]
                }
            ]
        },
        {
            "carrierCode": "dpd",
            "shippingMethods": [
                {
                    "type": "pickupPoint",
                    "subtypes": [
                        {
                            "code": "parcelMachine",
                            "rate": "3.00",
                            "currency": "EUR"
                        },
                        {
                            "code": "parcelShop",
                            "rate": "3.00",
                            "currency": "EUR"
                        }
                    ]
                }
            ]
        }
    ]
}

Response codes

Http code	Description
200	Returns calculated rates for all available carriers.

Response fields

Key	Type	Description
calculationDetails	object	Details about the parcel calculations.
calculationDetails.estimatedParcels	array	Estimated measurements for each parcel.
calculationDetails.estimatedParcels[].actualWeight	number	Actual weight in kg.
calculationDetails.estimatedParcels[].volumetricWeight	number	Volumetric weight in kg.
calculationDetails.estimatedParcels[].chargeableWeight	number	Chargeable weight (max of actual and volumetric).
calculationDetails.estimatedParcels[].bufferApplied	number	Buffer percentage applied to height for stacking.
destination	string	Destination country code.
carriers	array	List of carriers with their rates.
carriers[].carrierCode	string	Carrier code.
carriers[].shippingMethods	array	Available shipping methods with rates.
carriers[].shippingMethods[].type	string	Shipping method type: courier or pickupPoint.
carriers[].shippingMethods[].subtypes	array	Subtypes with individual rates.
carriers[].shippingMethods[].subtypes[].code	string	Subtype code (e.g., parcelMachine, standard).
carriers[].shippingMethods[].subtypes[].rate	string	Rate formatted to 2 decimal places.
carriers[].shippingMethods[].subtypes[].currency	string	Currency code (e.g., EUR).
carriers[].shippingMethods[].subtypes[].operators	array	Available operators for this subtype (optional).

Note

Rates are calculated based on your store’s contract pricing. When multiple items are in a parcel, heights are summed with a 15% buffer for stacking.

Create Shipment

The endpoint allows you to create a shipment for your store.

Endpoint path

POST /shipments

Authentication

Refer to the Authentication section. Follow instructions for GET endpoints.

Headers

Key	Required	Value
Authorization	yes	Bearer [your_token]

Body

Key	Type	Required	Value
merchantReference	string	no	Any reference or order ID that the merchant wants to use.
shippingMethod	object	yes	An object that defines the shipping method and optional additional services. Key Type Required Value type string yes Available values: courier, pickupPoint. id string yes The shipping method UUID (pickup point ID or courier service ID). additionalServices array no Optional additional services. See table below for structure. parcelHandoverMethod string no Unisend only. Values: courierPickUp, terminalDropOff. lockerSize string no Unisend only. Values: XS, S, M, L, XL. Additional services structure: Key Type Required Value code string yes Service type: cod (Cash on Delivery) or ageVerification. params object conditional Required for cod. Contains amount (number, 0.01-10000).
parcels	array	yes	The list of parcels. Below are the properties for a single parcel Key Type Required Value weight number yes 2. weight should be measured in kg. At the moment, only two digits are allowed after decimal. height number no 0.64. height should be measured in meters. At the moment, only two digits are allowed after decimal. width number no 0.38. width should be measured in meters. At the moment, only two digits are allowed after decimal. length number no 0.39. length should be measured in meters. At the moment, only two digits are allowed after decimal.
receiver	object	yes	Receiver information. Key Type Required Value firstName string no receiver’s first name. lastName string no receiver’s last name. name string yes receiver’s full name. streetAddress string conditional if shipping method is courier then it is mandatory. locality string conditional if shipping method is courier then it is mandatory. postalCode string conditional if shipping method is courier then it is mandatory. country string conditional if shipping method is courier then it is mandatory. phoneCountryCode string yes 372. Represents the country code for the phone number. phoneNumber string yes 5555555. Represents the phone number without the phone county code. region string no It represents the region of the address. email string no It represents the email address. companyName string no It represents company/business name of the receiver.
sender	object	no	Sender information. Key Type Required Value name string yes Represents sender’s full name. streetAddress yes conditional Represents the street address of the sender. locality string yes Represents the locality of the sender. postalCode string yes Represents the postalCode of the address. country string yes country code for the address. phoneCountryCode string yes 372. Represents the country code for the phone number. phoneNumber string yes 5555555. Represents the phone number without the phone county code. region string no It represents the region of the address. email string no It represents the email address. companyName string no It represents company/business name of the receiver.
products	array	no	List of shipped products. Adding products enables the pick list feature and displays products on the tracking page. Key Type Required Description sku string yes Product SKU identifier. Max 100 characters. name string yes Product name. Max 255 characters. quantity number yes Product quantity. Max value is 999. Decimals allowed. barcode string no Product barcode (any format). Max 100 characters. price number no Product unit price. Max 2 decimal places. currency string no ISO 4217 currency code (e.g., EUR, USD). attributes object no Custom attributes (e.g., {"color": "Red", "size": "M"}). Max 20 attributes. imageUrl string no URL to product image. Max 2048 characters. storeProductUrl string no URL to product page in your store. Max 2048 characters. description string no Product description. Max 5000 characters. HTML is stripped.
montonioOrderUuid	string	no	The UUID received from Montonio as a response to creating an order.
orderComment	string	no	Comment field, usually specified by customer.
synchronous	boolean	no	When set to true, the shipment will be registered synchronously and the response will include the final registration status. When false or omitted, the shipment is queued for asynchronous processing and returns with status pending. Default: false.

Additional Services Availability

Before including additional services in your shipment request, check their availability via the /shipping-methods/pickup-points or /shipping-methods/courier-services endpoints. Each pickup point and courier service includes an additionalServices array listing the available services.

Example request

curl -X 'POST' \
'https://shipping.montonio.com/api/v2/shipments' \
-H 'accept: application/json' \
-H 'Authorization: Bearer [your_token]' \
-H 'Content-Type: application/json' \
-d '{
    "sender": {
        "name": "Sender Y",
        "companyName": "Company Y",
        "streetAddress": "Kai 1",
        "locality": "Tallinn",
        "region": "Harjumaa",
        "postalCode": "10111",
        "country": "EE",
        "phoneCountryCode": "372",
        "phoneNumber": "53334770",
        "email": "support@montonio.com"
    },
    "receiver": {
        "name": "Receiver X",
        "companyName": "Company X",
        "streetAddress": "Kai 11",
        "locality": "Tallinn",
        "region": "Harjumaa",
        "postalCode": "10111",
        "country": "EE",
        "phoneCountryCode": "372",
        "phoneNumber": "53334770",
        "email": "support@montonio.com"
    },
    "merchantReference": "order 1",
    "shippingMethod": {
        "type": "courier",
        "id": "aeada198-fab7-4042-a414-82dcf3ea81e8",
        "additionalServices": [
            {
                "code": "cod",
                "params": { "amount": 25.50 }
            }
        ]
    },
    "parcels": [
        {
            "weight": 1
        }
    ],
    "products": [
        {
            "sku": "product-123",
            "name": "Blue Police Car",
            "quantity": 3,
            "barcode": "0123456789123",
            "price": 19.99,
            "currency": "EUR",
            "attributes": {
                "color": "Blue",
                "material": "Plastic"
            },
            "imageUrl": "https://example.com/images/blue-police-car.jpg"
        }
    ]
}'

Show / Hide Response Data

{
    "id": "4c1f8213-eec0-4ee6-8661-613eca9dd27e",
    "createdAt": "2024-06-14T13:03:49.039Z",
    "status": "pending",
    "montonioOrderUuid": null,
    "merchantReference": "order 1",
    "sender": {
        "id": "cc10856d-9e7d-4f3b-988f-eee0c10e8df8",
        "name": "Sender Y",
        "companyName": "Company Y",
        "streetAddress": "Kai 1",
        "locality": "Tallinn",
        "region": "Harjumaa",
        "postalCode": "10111",
        "country": "EE",
        "phoneCountryCode": "372",
        "phoneNumber": "53334770",
        "email": "support@montonio.com"
    },
    "receiver": {
        "id": "e75cf0f8-9417-456b-927b-1ac95bbbab49",
        "firstName": null,
        "lastName": null,
        "name": "Receiver X",
        "companyName": "Company X",
        "streetAddress": "Kai 11",
        "locality": "Tallinn",
        "region": "Harjumaa",
        "postalCode": "10111",
        "country": "EE",
        "phoneCountryCode": "372",
        "phoneNumber": "53334770",
        "email": "support@montonio.com"
    },
    "parcels": [
        {
            "id": "00b000c6-d694-4bb0-b1db-6159c45ffed2",
            "weight": 1,
            "length": null,
            "height": null,
            "width": null,
            "carrierParcelId": null,
            "trackingLink": null
        }
    ],
    "shippingMethod": {
        "id": "e61bef79-cfdc-462e-8d57-a77a0c54abba",
        "type": "pickupPoint",
        "carrierCode": "smartpost",
        "countryCode": "EE"
    },
    "carrierShipmentId": null,
    "store": {
        "id": "5d165f67-184f-451a-b819-214aabe25c00"
    },
    "products": [
        {
            "id": "64e917de-b662-478a-b123-b0bd099369d6",
            "createdAt": "2025-01-17T13:34:40.124Z",
            "sku": "product-123",
            "name": "Blue Police Car",
            "barcode": "0123456789123",
            "quantity": 3
        }
    ]
}

Response codes

Http code	Description
201	Shipment was successfully created.
409	Shipment already exists.
500	There was a problem with creating the shipment.

Update a shipment

This endpoint allows you to update a shipment. A shipment can only be updated when it’s in status registrationFailed or registered. It is currently not possible to update the shipment’s products.

Endpoint path

PATCH /shipments/{shipmentId}

Authentication

Refer to the Authentication section. Follow instructions for GET endpoints.

Headers

Key	Required	Value
Authorization	yes	Bearer [your_token]

Params

Key	Type	Required	Value
shipmentId	string	yes	The unique identifier of the shipment.

Body

Key	Type	Required	Value
shippingMethod	object	no	An object that defines the shipping method and optional additional services. See the Create Shipment section for the full structure including additionalServices, parcelHandoverMethod, and lockerSize.
parcels	array	no	The list of parcels. Below are the properties for a single parcel Key Type Required Value weight number yes 2. weight should be measured in kg. At the moment, only two digits are allowed after decimal. height number no 0.64. height should be measured in meters. At the moment, only two digits are allowed after decimal. width number no 0.38. width should be measured in meters. At the moment, only two digits are allowed after decimal. length number no 0.39. length should be measured in meters. At the moment, only two digits are allowed after decimal.
receiver	object	no	Receiver information. Key Type Required Value firstName string no receiver’s first name. lastName string no receiver’s last name. name string yes receiver’s full name. streetAddress string conditional if shipping method is courier then it is mandatory. locality string conditional if shipping method is courier then it is mandatory. postalCode string conditional if shipping method is courier then it is mandatory. country string conditional if shipping method is courier then it is mandatory. phoneCountryCode string yes 372. Represents the country code for the phone number. phoneNumber string yes 5555555. Represents the phone number without the phone county code. region string no It represents the region of the address. email string no It represents the email address. companyName string no It represents company/business name of the receiver.
sender	object	no	Sender information. Key Type Required Value name string yes Represents sender’s full name. streetAddress yes conditional Represents the street address of the sender. locality string yes Represents the locality of the sender. postalCode string yes Represents the postalCode of the address. country string yes country code for the address. phoneCountryCode string yes 372. Represents the country code for the phone number. phoneNumber string yes 5555555. Represents the phone number without the phone county code. region string no It represents the region of the address. email string no It represents the email address. companyName string no It represents company/business name of the receiver.

Example request

curl -X 'PATCH' \
'https://shipping.montonio.com/api/v2/shipments/7a6f087c-def0-4830-80af-55ccdf7df3fd' \
-H 'accept: application/json' \
-H 'Authorization: Bearer [your_token]' \
-H 'Content-Type: application/json' \
-d '{
   "receiver": {
      "name": "New Name for Receiver",
      "companyName": "New Company Name",
      "streetAddress": "street no 2",
      "locality": "Tallinn",
      "region": "Harjumaa",
      "postalCode": "10999",
      "country": "EE",
      "phoneCountryCode": "372",
      "phoneNumber": "58107505",
      "email": "someone@montonio.com"
   }
}'

Show / Hide Response Data

{
    "id": "7a6f087c-def0-4830-80af-55ccdf7df3fd",
    "createdAt": "2024-05-31T11:52:03.766Z",
    "status": "registered",
    "montonioOrderUuid": null,
    "merchantReference": "123456",
    "sender": {
        "id": "030ded90-16c3-44ad-a78a-15efaa298335",
        "name": "John",
        "companyName": "Smith",
        "streetAddress": "test street no 123",
        "locality": "Tallinn",
        "region": "Harjumaa",
        "postalCode": "10999",
        "country": "EE",
        "phoneCountryCode": "372",
        "phoneNumber": "55555555",
        "email": "someone@montonio.com"
    },
    "receiver": {
        "id": "504590f8-79e9-40f9-81b7-3ff15095dbef",
        "name": "New Name for Receiver",
        "firstName": null,
        "lastName": null,
        "companyName": "New Company Name",
        "streetAddress": "street no 2",
        "locality": "Tallinn",
        "region": "Harjumaa",
        "postalCode": "10999",
        "country": "EE",
        "phoneCountryCode": "372",
        "phoneNumber": "58107505",
        "email": "someone@montonio.com"
    },
    "parcels": [
        {
            "id": "46ae777e-67fa-4e62-9c37-04222aaee810",
            "weight": 2,
            "length": null,
            "height": null,
            "width": null,
            "carrierParcelId": "CC543130987EE",
            "trackingLink": "https://minu.omniva.ee/track/CC543130987EE?language=et"
        }
    ],
    "shippingMethod": {
        "id": "0ffb9b04-3927-462a-a393-4f1e21f2ee55",
        "type": "courier",
        "carrierCode": "omniva",
        "countryCode": "EE"
    },
    "carrierShipmentId": null,
    "store": {
        "id": "eb607940-7348-4ef7-a13f-d983c0637466"
    },
    "products": null
}

Response codes

Http code	Description
200	Shipment was successfully updated.
500	There was a problem while updating the shipment.

Get shipment details

The endpoint allows you to fetch the details of a shipment.

Endpoint path

GET /shipments/{shipmentId}

Authentication

Refer to the Authentication section. Follow instructions for GET endpoints.

Headers

Key	Required	Value
Authorization	yes	Bearer [your_token]

Params

Key	Type	Required	Value
shipmentId	string	yes	The unique identifier of the shipment.

Example request

curl -X 'GET' \
'https://shipping.montonio.com/api/v2/shipments/d10e4ed8-1776-4828-bde7-0eb95456e367' \
-H 'accept: application/json' \
-H 'Authorization: Bearer [your_token]'

Show / Hide Response Data

{
    "id": "d10e4ed8-1776-4828-bde7-0eb95456e367",
    "createdAt": "2024-05-31T13:11:10.307Z",
    "status": "labelsCreated",
    "montonioOrderUuid": null,
    "merchantReference": "1213321",
    "sender": {
        "id": "5d61c57b-151c-44b8-98b8-2715570534ab",
        "name": "John",
        "companyName": "Smith",
        "streetAddress": "test street no 123",
        "locality": "Tallinn",
        "region": "Harjumaa",
        "postalCode": "10999",
        "country": "EE",
        "phoneCountryCode": "372",
        "phoneNumber": "55555555",
        "email": "someone@montonio.com"
    },
    "receiver": {
        "id": "fb424f5d-acc8-4cf8-a21b-cecb5c3daacf",
        "firstName": "Joe",
        "lastName": "Smith",
        "companyName": "",
        "streetAddress": "test street",
        "locality": "tallinn",
        "region": "",
        "postalCode": "10615",
        "country": "EE",
        "phoneCountryCode": "372",
        "phoneNumber": "58107505",
        "email": "someone@montonio.com"
    },
    "parcels": [
        {
            "id": "0a3533e6-6a8c-4dfa-83b6-df76f8f74372",
            "weight": 2,
            "length": null,
            "height": null,
            "width": null,
            "carrierParcelId": "CC543167770EE",
            "trackingLink": "https://minu.omniva.ee/track/CC543167770EE?language=et"
        }
    ],
    "shippingMethod": {
        "id": "98b391d7-5299-447c-9ad7-6b4042ef8b2f",
        "type": "pickupPoint",
        "carrierCode": "omniva",
        "countryCode": "EE"
    },
    "carrierShipmentId": null,
    "store": {
        "id": "eb607940-7348-4ef7-a13f-d983c0637466"
    },
    "products": null
}

Response codes

Http code	Description
200	Returns the shipment details.
404	Shipment not found.

Create a label file

The endpoint allows you to create a label file for your shipments.

Note

Once the label is created, the label URL will last 5 minutes, after which it will no longer be accessible. To get a fresh URL, make a new request.

Endpoint path

POST /label-files

Authentication

Refer to the Authentication section. Follow instructions for GET endpoints.

Headers

Key	Required	Value
Authorization	yes	Bearer [your_token]

Body

Key	Type	Required	Value
shipmentIds	array	yes	An array of shipment ids.
pageSize	string	no	Available values: A4, A6.
labelsPerPage	number	no	Available values: 1, 4, 6, 8.
orderLabelsBy	string	no	Available values: carrier, createdAt.
synchronous	boolean	no	When set to true, the label file will be generated synchronously and the response will include the download URL. When false or omitted, label generation is queued and returns with status pending. Default: false.

Example request

curl -X 'POST' \
'https://shipping.montonio.com/api/v2/label-files' \
-H 'Authorization: Bearer [your_token]' \
-H 'Content-Type: application/json' \
-d '{
          "shipmentIds": [
               "d10e4ed8-1776-4828-bde7-0eb95456e367"
          ],
          "pageSize": "A4",
          "labelsPerPage": 1,
         "orderLabelsBy": "carrier"
}'

Show / Hide Response Data

{
  "id": "44cb7cbf-8ac9-48b8-ba9c-2162f8420885",
  "status": "pending",
  "pageSize": "A4",
  "labelsPerPage": "1",
  "orderLabelsBy": "carrier",
  "labelFileUrl": null
}

Response codes

Http code	Description
201	Shipping labels were successfully created.
400	Bad request, validation failed.
500	There was a problem creating the label file.

Get label file

The endpoint allows you to fetch the label file.

Note

Once the label is created, the label URL will last 5 minutes, after which it will no longer be accessible. To get a fresh URL, make a new request.

Endpoint path

GET /label-files/{labelFileId}

Authentication

Refer to the Authentication section. Follow instructions for GET endpoints.

Headers

Key	Required	Value
Authorization	yes	Bearer [your_token]

Params

Key	Type	Required	Value
labelFileId	string	yes	The ID of the label file.

Example request

curl -X 'GET' \
'https://shipping.montonio.com/api/v2/label-files/7e30e74e-88be-4ab6-a972-649993a616e1' \
-H 'accept: application/json' \
-H 'Authorization: Bearer [your_token]'

Show / Hide Response Data

{
  "id": "7e30e74e-88be-4ab6-a972-649993a616e1",
  "status": "ready",
  "pageSize": "A4",
  "labelsPerPage": "1",
  "orderLabelsBy": "carrier",
  "labelFileUrl": "https://shipping-v2-labels-production-s3.s3.eu-central-1.amazonaws.com/5decd9b6-4fa2-47cf-b045-d67444a8892a?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=ASIAXYMK66KJLORP5MVF%2F20240531%2Feu-central-1%2Fs3%2Faws4_request&X-Amz-Date=20240531T135149Z&X-Amz-Expires=300&X-Amz-Security-Token=IQoJb3JpZ2luX2VjEL3%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaDGV1LWNlbnRyYWwtMSJHMEUCIQDF0oYutWCaemuHRqKYK5nU3jkpb%2B4qlw91JLncABxzTQIgC6x5%2FBygSr0P8EEM%2BovhK4ejFO6K6IYsDtgpeU5oDUwq%2FgMIRxAAGgw1MzM0MDQyNTA3NzAiDEtk3DBxTr%2FeHcN%2F%2BSrbAxSJRJFElx4FEA4SmZNGbWQFQ6rer7Aare6c4uz23jEh1NJmZwubln9DMcRJ4eJu0MRJDADPJ4f1UFSRiLR7DamIyIYmWfxRt59DzLxwPM%2BfBPSqtjyWmSZGzlo4i4YTdJsMBNJjBcqrpCNqUjPPbLnzsEXfD%2F%2FC4FvdE0vri9lkNXB1n5Y1w9UmIiUjBbRpNpcP%2F1ECjElLq0OmewNMGsEYUA657YrnzAWvs8twp3kXN37l2KDWrIr5UDMBMvdKDa9%2BUQ2iTrzu2l1picGTRVZT%2BwHd5EmgSUWIYM%2BEMqRYbUPVolRkNoM4%2BYRSjGMyIvMkLoRllUMGCEjqYSQXezOHS%2BpkyebZ%2B4w4O1O64Eq5KqDH9lxMuvniAyvkvZL3WdeAOnKQHb9xOvsbxnHq3iEQQrnsyy7x98TpGqHAC0usnc6qDXrmNSDF5aogqOyVOzxfHQYp9nelDEIiSftH%2BeNUK2Bc0Nuy9InN2ugJ4DtCX4jBHidAoG3cQGSjZkHIXrs%2BRbxjy%2FOQ8RIO5YLZa1DiPf%2Fu%2BliAbVQsWR0ePGglfwQGMhUyrv3OM7%2Bcwe89o12raE2H2gy8Dcdlvwq9Ug2aoUCBaK755lY27sG5Ff4uFs3LxvsdqFd%2FnIIwv57nsgY6pQFTLH1wBVgy4Dgv7yUwqy2zthGlLAHPP3prKsnxhR6tydf9rB3isapsW3AJhy28buXPvKv0beYb5vteRsnIUybX8NPil7oWO6B8Z%2FDWVfzeZ0uw3tK%2BK4mAwtMAXvBjd73HX14NQ92OSp82tNzn8%2BwDt9aJjv7FKA8YY2fAM4Vl70rwL8j0VIlD9L6w%2BEcbNIurwNSIMPrHFMA3nFFogEB3muRcf0M%3D&X-Amz-Signature=da12ce556539809a27a053576b1831b4d8df2eec5de4f2013944154ad33c1fc2&X-Amz-SignedHeaders=host&x-id=GetObject"
}

Response codes

Http code	Description
200	Return the label file details.
500	There was a problem getting the label file.

Create webhooks

The endpoint allows you to create a webhook that can be used to subscribe to different events, such as shipment.registered, shipment.registrationFailed, shipment.labelsCreated, shipment.statusUpdated, labelFile.ready and labelFile.creationFailed.

Endpoint path

POST /webhooks

Authentication

Refer to the Authentication section. Follow instructions for GET endpoints.

Headers

Key	Required	Value
Authorization	yes	Bearer [your_token]

Body

Key	Type	Required	Value
url	string	yes	The notification URL for receiving updates.
enabledEvents	array	yes	Available values: shipment.registered, shipment.registrationFailed, shipment.labelsCreated, shipment.statusUpdated, labelFile.ready, labelFile.creationFailed.

Example request

curl -X 'POST' \
'https://shipping.montonio.com/api/v2/webhooks' \
-H 'accept: application/json' \
-H 'Authorization: Bearer [your_token]' \
-H 'Content-Type: application/json' \
-d '{
   "url": "http://partner.montonio/shipmentEvents",
   "enabledEvents": ["shipment.registered"]
}'

Show / Hide Response Data

{
  "id": "92965086-24a3-4fbd-919a-661142210c48",
  "createdAt": "2024-05-31T14:02:47.780Z",
  "url": "http://partner.montonio/shipmentEvents",
  "enabledEvents": [
    "shipment.registered"
  ]
}

Response codes

Http code	Description
201	Webhook was successfully created.
400	Bad request, validation failed.
403	Webhook limit has been reached. You can currently create a maximum of 10 webhooks per store.
409	Webhook already exists.
500	There was a problem creating the webhook.

Get all webhooks

The endpoint allows you to fetch all webhooks created for your store.

Endpoint path

GET /webhooks

Authentication

Refer to the Authentication section. Follow instructions for GET endpoints.

Headers

Key	Required	Value
Authorization	yes	Bearer [your_token]

Example request

curl -X 'GET' \
'https://shipping.montonio.com/api/v2/webhooks' \
-H 'accept: application/json' \
-H 'Authorization: Bearer [your_token]'

Show / Hide Response Data

{
  "data": [
    {
      "id": "92965086-24a3-4fbd-919a-661142210c48",
      "createdAt": "2024-05-31T14:02:47.780Z",
      "url": "http://partner.montonio/shipmentEvents",
      "enabledEvents": [
        "shipment.registered"
      ]
    }
  ]
}

Response codes

Http code	Description
200	Returns the list of webhooks for the store.
500	There was a problem fetching the webhooks.

Delete a webhook

The endpoint allows you to delete a webhook.

Endpoint path

DELETE /webhooks/{webHookId}

Authentication

Refer to the Authentication section. Follow instructions for GET endpoints.

Headers

Key	Required	Value
Authorization	yes	Bearer [your_token]

Params

Key	Required	Value
webHookId	yes	It represents the webhook id.

Example request

curl -X 'DELETE' \
'https://shipping.montonio.com/api/v2/webhooks/8724ef8b-aca4-4a2f-bf5b-074118f9adf6' \
-H 'accept: application/json' \
-H 'Authorization: Bearer [your_token]'

Show / Hide Response Data

200 Ok
{}

Response codes

Http code	Description
200	Webhook deleted successfully.
400	Bad request, validation failed.
500	There was a problem deleting the webhook.