Shipping
The Montonio Shipping API allows you to create and manage shipments with multiple carriers. This guide focuses on fetching and displaying shipping methods, registering shipments, and creating shipping labels. The Guides section contains detailed instructions and code examples on integrating with the API.
General flow to complete the integration
- Create a Webhook to receive notifications
- Retrieve available Shipping Methods for your store
- Create a Shipment
- Create a Label File
What is a Shipment?
A shipment can be viewed as a container containing the essential information about parcels that need to be delivered from point A to point B.
Before creating a shipment, you must retrieve your store’s available shipping methods. This will provide you with a list of options for transporting the parcels. To create a shipment, you must specify details such as sender and receiver information, a shipping method, and the parcels included in the Shipment. A shipment can contain one or more parcels. Once the Shipment is registered with the Carrier, you can create a label file for it. A label file can contain one or more shipping labels, which should be attached to the parcel.
What shipping methods can be used?
A Shipment can be delivered using one of the available methods, which should be specified when creating the Shipment. They are:
| Shipping method type | Examples |
|---|---|
| Courier | Standard courier |
| Pickup point | Parcel machine, parcel shop, post office |
What is the lifecycle of a Shipment?
By default, our API uses asynchronous processing to register shipments with carriers. This is the recommended approach as it provides robust handling of carrier API issues. For simpler integrations, you can opt for synchronous processing by setting synchronous: true - see the Shipments guide for details.
When using asynchronous processing, you must create a webhook to listen for shipment lifecycle events.
We use the status property to communicate a shipment’s status. You will receive a webhook notification via an HTTP POST request whenever a shipment transitions from one status to another.
You can expect the following values for status:
| Status | Description |
|---|---|
| pending | The Shipment has been created but is not yet registered with the Carrier. Shipment will be registered asynchronously. Label file cannot be created yet. |
| registered | Shipment has been registered with the Carrier. Label file creation is now possible. |
| registrationFailed | We could not register the shipment previously in status pending. |
| labelsCreated | A label file is successfully created for the Shipment. |
| inTransit | The Carrier picked up the Shipment from the sender. This means one or more parcels have been picked up and will be delivered to the receiver. |
| awaitingCollection | One or more parcels are ready to be picked up from the pickup point. This is only used for pickup point shipments. |
| delivered | All parcels are delivered to the receiver. |
| returned | One or more parcels are returned to the sender. |
What is the lifecycle of a Label File?
By default, we use asynchronous processing to create the label file. For simpler integrations, you can opt for synchronous processing by setting synchronous: true - see the Labels guide for details.
When using asynchronous processing, ensure you include the correct event type when creating a webhook.
A label file is a PDF that contains one or more shipping labels. To communicate the status of the label file generation process, we use the status property. Whenever a label file transitions from one status to another, you will receive a webhook notification via an HTTP POST request.
You can expect the following values for status:
| Status | Description |
|---|---|
| pending | The Label File entity is created, but the PDF file is not ready for download. The file creation process is asynchronous. |
| ready | The Label File is successfully generated and can now be downloaded. |
| failed | Label File generation failed. Under normal circumstances, this should not happen. |
How to access the API?
The 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 here.
To authenticate with the API, you’ll need to use API keys. Read more about API keys and how to get them. The authentication mechanism is described in the Authentication section of the API reference.
Getting started
To build your integration step-by-step, dive deeper into the Developer guides.
We also have a Swagger API reference, which you can find here.
Happy coding! 🚀