Retrieve and use the carrier setup file
This guide provides an overview of how to retrieve a JSON file containing details about your available carriers, products, and services using the API. If you are looking to avoid requesting individual endpoints for available carriers, -products, packages repeatedly, this method allows you to get all the necessary information at once. The file is ideal for those managing shipmondo through systems like WMS, ERP, or similar platforms.
By following the steps outlined here, you'll learn how to:
- Request the carrier setup file.
- Monitor the process while it’s being generated.
- Retrieve the finalized file.
- Understand the structure and contents of the file.
Overview of the carrier setup file - Shipmondo API
The endpoint for retrieving the carrier setup file is documented here. By making a request to this endpoint, you can retrieve a JSON file that includes all the information about your setup for carriers, products, services, etc.
How to retrieve the JSON-File configuration
Step 1: Request the carrier setup file
Endpoint
GET https://app.shipmondo.com/api/public/v3/setups/carriers
Response:
{
"status": "REQUESTED",
"expires_at": null,
"url": null
}
At this stage, Shipmondo will begin processing and generating your carrier setup file. The response indicates that the request has been accepted, but the file is not yet ready for download.
Step 2: Monitor the file generation
Depending on the complexity of your setup, the file generation process may take several minutes. You can monitor the progress by pinging the same endpoint at regular intervals, such as every 15 or 30 seconds. Keep in mind that excessive requests could cause the API to throttle your requests, so ping in moderation.
Endpoint
GET https://app.shipmondo.com/api/public/v3/setups/carriers
Response:
{
"status": "IN_PROGRESS",
"expires_at": null,
"url": null
}
When the status is "IN_PROGRESS," it indicates that the file is still being generated.
Step 3: Retrieve the completed file
Once the file is generated, the API will return a response with a download URL. At this point, you can retrieve the complete carrier setup file.
Endpoint
GET https://app.shipmondo.com/api/public/v3/setups/carriers
Response:
{
"status": "COMPLETED",
"expires_at": "2024-01-01T01:01:01Z",
"url": "<link_to_file>"
}
The file is ready to be downloaded via the url provided in the response. The expires_at field indicates when the URL will expire, so make sure to download it before that time.
Step 4: Downloading the file
To retrieve the full carrier setup file, send a GET request to the url before it expires. The file can be quite large (up to several megabytes), so consider streaming the response if you're concerned about payload size.
If necessary, you can use a Range header to stream the response and retrieve it in chunks.
File structure and content
Prerequisites
When reading this, you should be familiar with creating shipments with Shipmondos API. The purpose of the data and structure of the file is to use it directly to manage shipments.
High-Level overview
The JSON file you retrieve will contain a hierarchical structure detailing all the carriers, products, and services associated with your account. Below is a simplified representation of the file structure:
Carrier [1..n]
├── Product [1..n]
├── Country Combination Specifics [1..n]
├── Available Services [0..n]
└── Required Services [0..n]
This structure allows you to easily identify the relationships between carriers, products, country combinations, and the available and required services for each. For example, you can see how many products you have available for a carrier and which services are available for different countries.
Detailed breakdown of the file structure
1. Carriers
Each object represents carriers available to you:
[
{
"code": "gls",
"name": "GLS Denmark",
"products": [{ ... }]
},
{
"code": "post_nord",
"name": "PostNord (SE, NO, FI)",
"products": [{ ... }]
},
]
2. Products
Within each carrier, there are multiple products available for you.
{
"code": "gls",
"name": "GLS Denmark",
"products": [
{
"name": "Shop Delivery",
"code": "GLSDK_SD",
"service_point_product": true,
"country_combinations": [{ ... }]
},
{
"name": "Private Delivery Parcel",
"code": "GLSDK_HD",
"service_point_product": false,
"country_combinations": [{ ... }]
}
]
}
3. Country combinations
Each product can be available for shipping between specificcountry_combinations. It contains all the details specific to a country combination meaning sender_country_code and receiver_country_code.
{
"name": "Shop Delivery",
"code": "GLSDK_SD",
"service_point_product": true,
"country_combinations": [
{
"sender_country_code": "DK",
"receiver_country_code": "FI",
"shipmondo_agreement_available": true,
"own_agreement_available": true,
"available_customer_numbers": [
"56212"
],
"customs_declaration_required": false,
"required_fields": ["receiver_email"],
"optional_fields": ["receiver_attention"],
"required_parcel_fields": ["quantity", "weight"],
"optional_parcel_fields": ["height", "length", "width"],
"optional_dg_fields": [],
"package_types": [],
"allowed_incoterms": [],
"available_services": [{ ... }],
"required_services": [{ ... }]
}
]
}
Special fields:
shipmondo_agreement_available: If true, a shipment can be created with Shipmondos freight agreement and vice versa.own_agreement_available: If true, a shipment can be created with your own freight agreement, using one of the customer numbers inavailable_customer_numbers.
4. Required and available services
Example of available and required services under a country_combination.
{
...
"available_services": [{
"code": "INSR_10000",
"name": "Forsikring op til 10.000 DKK",
"required_fields": [],
"optional_fields": [],
"own_agreement_required": false
},
{
"code": "INSR_20000",
"name": "Forsikring op til 20.000 DKK",
"required_fields": [],
"optional_fields": [],
"own_agreement_required": false
}],
"required_services": [{
"code": "EMAIL_NT",
"name": "E-mail advisering",
"required_fields": ["receiver_email"],
"optional_fields": [],
"own_agreement_required": false,
"note": "E-mail advisering er påkrævet"
},
{
"code": "SMS_NT",
"name": "SMS advisering",
"required_fields": ["receiver_mobile"],
"optional_fields": [],
"own_agreement_required": false,
"note": "SMS advisering er påkrævet"
}]
}
Full example
[
{
"code": "gls",
"name": "GLS Denmark",
"products": [
{
"name": "ShopDelivery",
"code": "GLSDE_SD",
"service_point_product": true,
"country_combinations": [
{
"sender_country_code": "DK",
"receiver_country_code": "FI",
"shipmondo_agreement_available": true,
"own_agreement_available": true,
"available_customer_numbers": ["56212"],
"customs_declaration_required": false,
"required_fields": ["receiver_email"],
"optional_fields": ["receiver_attention"],
"required_parcel_fields": ["quantity", "weight"],
"optional_parcel_fields": ["height", "length", "width"],
"optional_dg_fields": [],
"package_types": [],
"allowed_incoterms": [],
"available_services": [
{
"code": "INSR_10000",
"name": "Forsikring op til 10.000 DKK",
"required_fields": [],
"optional_fields": [],
"own_agreement_required": false
},
{
"code": "INSR_20000",
"name": "Forsikring op til 20.000 DKK",
"required_fields": [],
"optional_fields": [],
"own_agreement_required": false
}
],
"required_services": [
{
"code": "EMAIL_NT",
"name": "E-mail advisering",
"required_fields": ["receiver_email"],
"optional_fields": [],
"own_agreement_required": false,
"note": "E-mail advisering er påkrævet"
},
{
"code": "SMS_NT",
"name": "SMS advisering",
"required_fields": ["receiver_mobile"],
"optional_fields": [],
"own_agreement_required": false,
"note": "SMS advisering er påkrævet"
}
]
}
]
}
]
}
]