Creating a Label File

This guide will walk you through creating a Label File using the Montonio API. More information can be found in the API reference.

Creating a Label File

You need to attach shipping labels to ensure parcels can be shipped. Use the POST /label-file API to create a Label File, which can contain one or more shipping labels.

Each label is linked to a parcel, ensuring each parcel has a unique label. To generate a label file, include the Shipment ID(s) in the request body. For example, if your shipment includes two parcels, send a POST request to the /label-file API with the Shipment ID in the request body. Because the file generation process is asynchronous, the API response will provide the Label File object’s ID and indicate a pending status.

Once the file is generated, you will receive a webhook notification with the URL to download the PDF containing the label(s). Before creating a label file, ensure that the shipments included in the request have a registered status.

Complete example

This is a complete example of how to create a Label File. Before continuing, make sure that all shipments for which you wish to get the shipping label are in status registered. The process is as follows:

1. Gather all shipment IDs for which you wish to get the labels. The Label File can contain up to 100 shipments, and each shipment can contain one or several parcels.
2. Specify the optional configuration settings for the file. Below is an overview of these options and what they mean:

Option	Description
pageSize	The size of the label file page. It can be either “A6” or “A4”.
labelsPerPage	Specifies how many labels can be placed on each page. The options are 1, 4, 6 and 8.
orderLabelsBy	Order the labels by carrier name or createdAt date. Can be either “carrier” or “createdAt”

JavaScript

import axios from 'axios';

const data = JSON.stringify({
    shipmentIds: ['1f83f4c1-cccc-4dd5-8eae-837e6a88362f'],
    pageSize: 'A4',
    labelsPerPage: 4,
    orderLabelsBy: 'createdAt',
});

const config = {
    method: 'post',
    url: 'https://shipping.montonio.com/api/v2/label-files',
    headers: {
        'Content-Type': 'application/json',
        Authorization: 'Bearer [your_token]',
    },
    data: data,
};

async function makeRequest() {
    try {
        const response = await axios.request(config);
        console.log(JSON.stringify(response.data));
    } catch (error) {
        console.log(error);
    }
}

makeRequest();

The example API response will be the following:

{
    "id": "d58f2e2f-7460-4916-8463-8644f917b22b",
    "status": "pending",
    "pageSize": "A4",
    "labelsPerPage": 4,
    "orderLabelsBy": "createdAt",
    "labelFileUrl": null
}

The Label File object can go into one of the following statuses:

Status	Description
pending	Label File creation is in progress and the PDF file cannot be downloaded yet. The file creation process is asynchronous.
ready	Label File is successfully generated and can now be downloaded.
failed	Label File generation failed. In normal circumstances, this should not happen.

Synchronous vs Asynchronous Flow

By default, label files are generated asynchronously. When you create a label file, it returns immediately with status pending, and the actual file generation happens in the background. You receive a webhook notification when the status changes to ready or failed.

For simpler integrations, you can opt for synchronous processing by setting synchronous: true in your request. This makes the API wait for the label file to be generated before returning, so you get the download URL directly in the response.

Choosing Between Sync and Async Flows

Asynchronous (Default): Recommended for most integrations. Provides robust handling when generating labels for many shipments. Requires setting up webhooks to receive the label file URL.

Synchronous: Simpler to implement as no webhooks are required for label file URL. Best suited for low-volume stores or when generating labels for a small number of shipments. Note that requests may timeout if generating labels for many shipments at once.

Synchronous example

JavaScript

import axios from 'axios';

const data = JSON.stringify({
    shipmentIds: ['1f83f4c1-cccc-4dd5-8eae-837e6a88362f'],
    pageSize: 'A4',
    labelsPerPage: 4,
    orderLabelsBy: 'createdAt',
    synchronous: true, // Enable synchronous processing
});

const config = {
    method: 'post',
    url: 'https://shipping.montonio.com/api/v2/label-files',
    headers: {
        'Content-Type': 'application/json',
        Authorization: 'Bearer [your_token]',
    },
    data: data,
};

async function makeRequest() {
    try {
        const response = await axios.request(config);
        // Response will have status "ready" and include the labelFileUrl directly
        console.log(JSON.stringify(response.data));
    } catch (error) {
        console.log(error);
    }
}

makeRequest();

With synchronous processing, the response will include the download URL:

{
    "id": "d58f2e2f-7460-4916-8463-8644f917b22b",
    "status": "ready",
    "pageSize": "A4",
    "labelsPerPage": 4,
    "orderLabelsBy": "createdAt",
    "labelFileUrl": "https://shippingv2-labels-live-production-s3.s3.eu-central-1.amazonaws.com/..."
}

Webhook notification

To continue the previous example, a Label File can go from the status pending to the status ready or failed. We will send a Webhook notification when this happens, so make sure you check out the guide on webhooks.

Fetching a Label File

Once the Label File is ready, you can download the file by fetching the Label File object and extracting the value of the labelFileUrl property.

JavaScript

import axios from 'axios';

const config = {
    method: 'get',
    url: 'https://shipping.montonio.com/api/v2/label-files/f8d8c402-0535-413f-b723-fd1101f2b580',
    headers: {
        Authorization: 'Bearer [your_token]',
    }
};

async function makeRequest() {
    try {
        const response = await axios.request(config);
        console.log(JSON.stringify(response.data));
    }
    catch (error) {
        console.log(error);
    }
}

makeRequest();

The example API response will be the following:

{
    "id": "f8d8c402-0535-413f-b723-fd1101f2b580",
    "status": "ready",
    "pageSize": "A4",
    "labelsPerPage": 4,
    "orderLabelsBy": "createdAt",
    "labelFileUrl": "https://shippingv2-labels-live-production-s3.s3.eu-central-1.amazonaws.com/3bfe0cdb-98ee-407..."
}

Some errors which might occur during the request are listed below:

Code	Description
400	Bad request. Please double-check the request body. You will get a more detailed error message.
401	Unauthorized. Please check if the JWT was generated correctly and the accessKey and secretKey are correct.
500	Internal server error. Something went wrong on our side.