Skip to main content

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",
		"country_combinations": [{ ... }]
	},
	{
		"name": "Private Delivery Parcel",
		"code": "GLSDK_HD",
		"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",
	"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 in available_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",
		"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"
			}]
		}]
	}]
}]