Qargo TMS Customer API (1.2.0)

Customer Portal API documentation

What's new — see the Changelog for recent additions and changes to the API.

Authentication

The api requires oauth2 authentication with client id/secret. This should only be used for service to service communication.

Creating application credentials

Application client credentials can be created by users with the Super admin role in the Qargo application. Users can create and remove application clients by navigating to Configuration -> Organisation Settings (API clients sections).

Applications need to be linked to a valid integration id, identifying the Qargo approved integrator. Please contact us if you don't have an id yet.

Obtaining an access token

To interact with the API, you need a valid access token in JWT (JSON Web Token) format. This token authenticates your requests and authorizes access to protected endpoints. The process involves using Basic Authentication to request the token via the /auth/token endpoint.

The /auth/token endpoint can be used to generate an access token (JWT):

This token will need to be refreshed after expiration (we provide the 'expires_in' in the token response to check validity).

Understanding Basic Authentication

Basic Authentication is a simple HTTP authentication scheme that allows clients to provide credentials (such as a client ID and secret) directly in the request header. It works by encoding the credentials in Base64 and including them in the Authorization header of the HTTP request. For example:

Format: Authorization: Basic <base64-encoded-credentials>
Credentials Encoding: The client ID and secret are concatenated with a colon (e.g., client_id:secret_id) and then Base64-encoded.

The API Call to Request Tokens

The /auth/token endpoint is a POST request used to generate a JWT access token. You authenticate this request using Basic Auth with your provided client_id and secret_id.

Request Details

Method: POST
URL: https://api.qargo.com/v1/auth/token
Headers:
- Content-Type: application/json
- Authorization: Basic <base64-encoded-client_id:secret_id>
Body: Empty.
Parameters: None.

Example using curl:

curl -XPOST https://api.qargo.com/v1/auth/token -H 'Content-type: application/json' -u '<client_id:secret_id>'

Webhook authentication

Important: Webhook endpoints use a different authentication method than regular API endpoints. Do not use OAuth tokens for webhooks.

Qargo webhooks, such as those for order import and status updates, use Basic Authentication instead of OAuth. See Understanding Basic Authentication for details on the Basic Auth scheme.

Webhook credentials (client id and secret id) are provisioned by Qargo when your webhook integration is configured — contact integrations@qargo.com to obtain them. They are separate from your API credentials and must be used exclusively for webhook endpoints.

API vs Webhook authentication summary

	API endpoints	Webhook endpoints
Auth method	OAuth2 (Client Credentials)	Basic Authentication
Credentials	API client_id + secret_id → Bearer JWT token	Webhook client_id + secret_id (directly in header)
Header format	`Authorization: Bearer <jwt_token>`	`Authorization: Basic <base64(client_id:secret_id)>`
Where to find credentials	Configuration → Organisation Settings → API clients	Provisioned by Qargo — contact integrations@qargo.com
Token refresh needed?	Yes (JWT expires)	No (credentials sent with each request)

Common mistake

Webhook credentials can technically be used to obtain an OAuth token via the /auth/token endpoint, but this token will not work for authenticating webhook requests. Always use Basic Authentication with your webhook credentials directly in the Authorization header.

Example webhook request

curl -XPOST https://api.qargo.com/v1/webhook/order-import \
  -H 'Content-Type: application/json' \
  -u '<webhook_client_id>:<webhook_secret_id>' \
  -d '{ ... }'

Rate Limits

To maintain API stability and prevent abuse, we enforce rate limits on a per-tenant basis.

Limits

The limits below are estimates based on normal operating conditions. Under increased system load, these limits may be tightened without prior notice to protect API stability.

Category	Scope	Limit
Authentication	`/auth/token`	5 requests per hour
General API Usage	All endpoints except authentication and webhooks	2 requests per second (sustained); up to 3 per second (bursts)

Enforcement

Rate limits are enforced by tracking requests over several sliding time windows-per second, per 10 minutes, and per hour. Exceeding any of these limits will result in an HTTP 429 Too Many Requests response. The response includes a Retry-After header specifying the number of seconds your application should wait before making a new request.

Timeline showing how to pace API requests, wait with jitter after a 429 response, and retry successfully

Example response:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 58

{"error":"Rate limit exceeded"}

Applications must handle this response correctly by treating Retry-After as the minimum delay, regardless of whether the request appeared to be within the estimated limits. If multiple workers or processes can make requests for the same tenant, add a small positive random delay (jitter) after Retry-After before retrying. Never subtract jitter or retry earlier than indicated. If another 429 response is returned, repeat this process using the latest Retry-After value.

For any concerns about these limits, please contact us at integrations@qargo.com.

API Best Practices

This section outlines recommended practices for efficiently working with the Qargo API.

Pagination

Some list endpoints support cursor-based pagination. Paginated responses contain items and next_cursor. When next_cursor is not null, pass its value unchanged as the cursor query parameter in the next request. Do not combine cursor with other query parameters.

How pagination works

Initial request: Make a request to a paginated endpoint without a cursor parameter.
Process the response: Read the current page from items.
Subsequent requests: If next_cursor is not null, pass its value as the cursor parameter in the next request.
Stop: Repeat until next_cursor is null.

Example usage

GET /v1/resources/resource

Response:

{
  "items": [
    {
      "name": "Truck 142",
      "row_id": "3f9e6b1c-3333-4d2e-b1a4-7c8f9e0a1b03"
    }
  ],
  "next_cursor": "eyJwYXJhbWV0ZXJzIjp7fSwic3RhdGUiOiJhYmMxMjM0NSIsImN1cnNvcl9zb3J0IjoiMjAyNi0wOC0xMlQxMDowMDowMFoiLCJjdXJzb3JfaWQiOiIzZjllNmIxYy0zMzMzLTRkMmUtYjFhNC03YzhmOWUwYTFiMDMifQ=="
}

Next request:

GET /v1/resources/resource?cursor=eyJwYXJhbWV0ZXJzIjp7fSwic3RhdGUiOiJhYmMxMjM0NSIsImN1cnNvcl9zb3J0IjoiMjAyNi0wOC0xMlQxMDowMDowMFoiLCJjdXJzb3JfaWQiOiIzZjllNmIxYy0zMzMzLTRkMmUtYjFhNC03YzhmOWUwYTFiMDMifQ==

The next page can be empty. Continue until the response returns next_cursor as null.

Recommendations

Check that next_cursor is not null before making another request.
Treat cursors as opaque. Do not parse, modify, or construct them.
Do not combine cursor with other query parameters.

Backward compatibility

The Qargo API follows these backward compatibility principles:

New fields may be added to response payloads at any time. Adding new fields is not considered a breaking change.
Integrators should ignore unknown fields when parsing responses. Do not fail on unexpected properties.
Deprecated fields and endpoints are marked as deprecated in this specification. They continue to work but may be removed in a future version. Migrate to the recommended replacement as soon as possible.
Existing fields will not be renamed or removed without prior notice and a deprecation period.

Date and time formats

All date and time fields in the API follow ISO 8601:

Type	Format	Example	Description
Date	`YYYY-MM-DD`	`2024-12-31`	Calendar date without time component
Datetime	`YYYY-MM-DDTHH:mm:ssZ`	`2024-12-31T14:30:00Z`	Timestamp in UTC (indicated by `Z` suffix)
Time	`HH:mm`	`09:30`	Time of day in 24-hour format

Datetime fields are always in UTC. Convert to local time on the client side.
Date fields have no timezone. They represent a calendar date (e.g. a planned delivery date).
Time fields are used for time windows (e.g. delivery windows) and are in 24-hour format without seconds.

Concepts

Company

A company in Qargo can be both a customer as well as a subcontractor (supplier). The entity will have a single id within Qargo. The api client can link companies by this id, or by the accounting code, which is a user defined code field.

Order

Transport order to execute. Also called job in other TMS systems. It contains all transport details:

Order references
Customer company
Consigments, with their stop locations, time windows, references
Definition of the goods to transport

Stop

A stop is a part of a transport, at a certain date, optional timeslot and location. In addition to the planned times, it also tracks the actual times for a completed stop. Stops can be linked to orders, or can be defined standalone (for example a cleaning stop). All stops are linked to a Trip.

Stop group

Stops can be grouped together according to their activity and location. This is called a stop group.

Trip

A trip contains stops from various orders, or standalone stops. It tracks how a certain transport is planned, and who will execute that transport.

Task

A task is the primary workflow concept in Qargo. Users can define their own flow, using both built-in tasks as well a custom defined ones. For the current accounting use case, we only expose the post invoice/credit note task, that allows users to send invoices to an accounting system.

Resource

A resource in Qargo is a vehicle, driver, trailer or other entity that can be assigned to a trip.

Unavailability

An unavailability indicates that a specific resource is not available for use for a given time range. An unavailability has a reason to indicate why the resource is not available.

Status update

A status update reflects a status change in an entity.

Document

A document in Qargo can be identified by a unique id. It has a type and is linked to a certain entity (for example an order).

Transport order creation & status

This sections details how to construct payloads to create transport orders using the order upload endpoint(/orders/order/upload).

Order creation metadata

Orders are not created synchronously via the API. When creating orders via the POST /orders/order/upload endpoint, you will receive the following response when creating an order.

{
  "upload_id": "<UPLOAD UUID>",
  "upload_status": "IN_PROGRESS",
  "upload_url": "v1/orders/order/upload/<UPLOAD UUID>",
  "order_id": null,
  "order_url": null
}

You need to store the upload_id so you can fetch the status of the order creation by calling GET /orders/order/upload/<UPLOAD UUID>

Based on the status of the upload (upload_status), you can know if the order is still in the progress of being created or has already been created. Both order_id and order_url will be filled in when the order has been created. The order_id will be filled in with the order id, which can then be used to fetch the order data and status from the system.

Example payload GET /orders/order/upload/e01b3db1-4e49-4241-a91e-7534da884d46 with a created order

{
  "upload_id": "e01b3db1-4e49-4241-a91e-7534da884d46",
  "upload_status": "COMPLETED",
  "upload_url": "v1/orders/order/upload/e01b3db1-4e49-4241-a91e-7534da884d46",
  "order_id": "a2a84715-0027-49af-ad30-494c0ccf75cc",
  "order_url": "v1/orders/order/a2a84715-0027-49af-ad30-494c0ccf75cc"
}

Order identifier

The order_identifier is used to uniquely identify orders that are being created via the API. This means that the same order_identifier needs to be used when updating orders. Multiple identical updates after each other are idempotent and will not fail the request.

The order_identifier main usage is for deduplication, you cannot use the order_identifier to fetch an order.

Create an order

The first example is a simple transport from our london office to our Ghent office. Please note that the transport service will need to be matched with the one in your system.

{
  "operation": "CREATE",
  "consignments": [
    {
      "delivery_stop": {
        "date": "2022-05-03",
        "location": {
          "name": "Qargo Ghent office",
          "address": "Gaston Crommenlaan 4",
          "postal_code": "9050",
          "city": "Ghent",
          "country": "BE"
        },
        "reference_number": "D12345"
      },
      "pickup_stop": {
        "date": "2022-04-21",
        "location": {
          "name": "Qargo London office",
          "address": "71-91 Aldwych",
          "postal_code": "WC2B 4HN",
          "city": "London",
          "country": "UK"
        },
        "reference_number": "P123456"
      }
    }
  ],
  "customer_reference_number": "T12345",
  "customer": {
    "code": "00020"
  },
  "order_identifier": "T1234393",
  "transport_service": {
    "name": "General"
  }
}

Note: it is possible to 'export' existing orders in the api to use as examples/templates. See the Export existing orders section.

Update an order

The following order is an update of an existing order. Note the UPDATE value of the operation field.

Important remarks:

Not all the fields of the order can be updated
the order_identifier field is used to identify the order to update

Example of an order update

{
  "order_identifier": "QARGO_TEST_0001",
  "operation": "UPDATE",
  "customer": {
    "name": "UPS SCS Coventry"
  },
  "consignments": [
    {
      "pickup_stop": {
        "location": {
          "name": "Qargo HQ",
          "address": "Gaston Crommenlaan 4,",
          "postal_code": "9000",
          "city": "Gent",
          "state": "Oost-Vlaanderen",
          "country": "BE",
          "description": "Qargo HQ building"
        },
        "note": "Pickup 4 boxes of pasta",
        "date": "2024-08-20",
        "reference_number": "QACOLLI001",
        "planning_instructions": "If closed, call mobile number",
        "email": "info@qargo.com",
        "phone_number": "+0912341431",
        "mobile_number": "+324567890"
      },
      "delivery_stop": {
        "location": {
          "name": "Grocery store",
          "address": "Resedastraat 20",
          "postal_code": "9000",
          "city": "Gent",
          "state": "Oost-Vlaanderen",
          "country": "BE",
          "description": "Grocery store"
        },
        "note": "Don't forget to sign the documents",
        "date": "2024-08-21",
        "reference_number": "QADELIV001",
        "planning_instructions": "Alarm code: 123456",
        "email": "info@qargo.com",
        "phone_number": "02123456",
        "mobile_number": "+329998888"
      },
      "goods": [
        {
          "description": "4 boxes of pasta",
          "quantity": 4
        }
      ]
    }
  ],
  "customer_reference_number": "QARGO_TEST_0001",
  "transport_service": {
    "code": "CONTAINER_BOOKING"
  }
}

Cancel an order

To cancel an order, pass DELETE as operation value. This will cancel the order. If the order has already been cancelled, this will not result in an error. Executing multiple cancellations is a idempotent operation and will not fail the request.

A cancelled order cannot be uncancelled. If you need to revert the cancel, you will need to recreate the original order using a different order identifier. Using the same order identifier will cause the system to try to update the cancelled order, which results in an error.

{
  "operation": "DELETE",
  "consignments": [
    {
      "delivery_stop": {
        "date": "2022-05-03",
        "location": {
          "name": "Qargo Ghent office",
          "address": "Gaston Crommenlaan 4",
          "postal_code": "9050",
          "city": "Ghent",
          "country": "BE"
        },
        "reference_number": "D12345"
      },
      "pickup_stop": {
        "date": "2022-04-21",
        "location": {
          "name": "Qargo London office",
          "address": "71-91 Aldwych",
          "postal_code": "WC2B 4HN",
          "city": "London",
          "country": "UK"
        },
        "reference_number": "P123456"
      }
    }
  ],
  "customer_reference_number": "T12345",
  "customer": {
    "code": "00020"
  },
  "order_identifier": "T1234393",
  "transport_service": {
    "name": "General"
  }
}

Export an existing order

It is possible to export a manually created order in the api. We first need to determine the technical id of this order.

Retrieve order id .

The order can be exported with the following endpoint: Export order. The output of this endpoint corresponds to the order creation format. Just make sure to use a different order_identifier, otherwise the 'new' order will be interpreted as an update.

Fetch order data and status

With the GET /orders/order/<ORDER UUID> endpoint, you can fetch the data related to the order. This contains the current status of the order along with other data.

Container orders

There are 2 types of container orders that can be created using the API, IMPORT and EXPORT.

Import

This scenario contains of 2 main stops additional optional stops.

Pickup of a loaded container
Unload container
Drop off empty container (Optional, configured in teardown_stops)

The container_scenario property is set as IMPORT and the drop off location of the container is specified in the the teardown_stops property. The optional teardown_stops describe the stops of the container after the consignment has been completed

Example IMPORT container scenario

{
  "order_identifier": "QARGO_TEST_0002",
  "operation": "CREATE",
  "customer": {
    "name": "UPS SCS Coventry"
  },
  "teardown_stops": [
    {
      "location": {
        "name": "Container yard",
        "address": "Scheepzatestraat 1",
        "postal_code": "9000",
        "city": "Gent",
        "state": "Oost-Vlaanderen",
        "country": "BE"
      },
      "note": "Drop off the container on the designated location",
      "date": "2024-08-20",
      "reference_number": "CONT0001",
      "planning_instructions": "Put next to the red container",
      "email": "info@qargo.com",
      "phone_number": "+0912341431",
      "mobile_number": "+324567890"
    }
  ],
  "consignments": [
    {
      "pickup_stop": {
        "location": {
          "name": "Container pickup location",
          "address": "Gaston Crommenlaan 4,",
          "postal_code": "9000",
          "city": "Gent",
          "state": "Oost-Vlaanderen",
          "country": "BE",
          "description": "This is the container pickup location"
        },
        "note": "Pick up the green container",
        "date": "2024-08-20",
        "reference_number": "CONT0002",
        "planning_instructions": "Code of the container is 1234",
        "email": "info@qargo.com",
        "phone_number": "+0912341431",
        "mobile_number": "+324567890"
      },
      "delivery_stop": {
        "location": {
          "name": "Sports store",
          "address": "Resedastraat 20",
          "postal_code": "9000",
          "city": "Gent",
          "state": "Oost-Vlaanderen",
          "country": "BE",
          "description": "This is the delivery location of the container goods"
        },
        "note": "1000 boxes of shoes",
        "date": "2024-08-21",
        "reference_number": "CONT0003",
        "planning_instructions": "Use mobile number if gate is closed",
        "email": "info@qargo.com",
        "phone_number": "02123456",
        "mobile_number": "+329998888"
      }
    }
  ],
  "container": {
    "container_scenario": "IMPORT"
  },
  "customer_reference_number": "QARGO_TEST_0002",
  "transport_service": {
    "code": "CONTAINERS"
  }
}

Export

This scenario contains 2 main stops with additional optional stops:

Pickup empty container (Optional, configured in setup_stops)
Load empty container
Drop off loaded container

The container_scenario is set as EXPORT and the setup_stops property allows to define additional optional stops.

Example of an EXPORT container_scenario

{
  "order_identifier": "QARGO_TEST_0003",
  "operation": "CREATE",
  "customer": {
    "name": "UPS SCS Coventry"
  },
  "setup_stops": [
    {
      "location": {
        "name": "Container yard",
        "address": "Scheepzatestraat 1",
        "postal_code": "9000",
        "city": "Gent",
        "state": "Oost-Vlaanderen",
        "country": "BE"
      },
      "note": "Pickup empty container on the designated location",
      "date": "2024-08-20",
      "reference_number": "CONT0001",
      "planning_instructions": "Blue container, next to the red container",
      "email": "info@qargo.com",
      "phone_number": "+0912341431",
      "mobile_number": "+324567890"
    }
  ],
  "consignments": [
    {
      "pickup_stop": {
        "location": {
          "name": "Container loading location",
          "address": "Gaston Crommenlaan 4,",
          "postal_code": "9000",
          "city": "Gent",
          "state": "Oost-Vlaanderen",
          "country": "BE",
          "description": "Qargo HQ, has a container loading bay"
        },
        "note": "Fill with 1000 boxes of Qargo shirts",
        "date": "2024-08-20",
        "reference_number": "CONT0002",
        "planning_instructions": "Code of the container is 1234",
        "email": "info@qargo.com",
        "phone_number": "+0912341431",
        "mobile_number": "+324567890"
      },
      "delivery_stop": {
        "location": {
          "name": "Train station container hub",
          "address": "Resedastraat 20",
          "postal_code": "9000",
          "city": "Gent",
          "state": "Oost-Vlaanderen",
          "country": "BE",
          "description": "This is the dropoff location of the loaded container"
        },
        "note": "1000 boxes of shoes",
        "date": "2024-08-21",
        "reference_number": "CONT0003",
        "planning_instructions": "Use mobile number if gate is closed",
        "email": "info@qargo.com",
        "phone_number": "02123456",
        "mobile_number": "+329998888"
      }
    }
  ],
  "container": {
    "container_scenario": "EXPORT"
  },
  "customer_reference_number": "QARGO_TEST_0003",
  "transport_service": {
    "code": "CONTAINERS"
  }
}

Create a loaded container import transport order

The following order picks up a filled container, delivers it to our office, and returns the empty container. This examples also demonstrates how to model ADR information.

{
  "operation": "CREATE",
  "consignments": [
    {
      "delivery_stop": {
        "location": {
          "name": "Qargo Ghent office",
          "address": "Gaston Crommenlaan 4",
          "postal_code": "9050",
          "city": "Ghent",
          "country": "BE"
        },
        "note": "unloading address comments",
        "reference_number": "D123956"
      },
      "pickup_stop": {
        "location": {
          "address": "Europaweg",
          "city": "Rotterdam",
          "country": "NL",
          "name": "APM terminals Maasvlakte II"
        },
        "reference_number": "P123956"
      },
      "goods": [
        {
          "good_items": {
            "adr": {
              "name": "DISINFECTANT, LIQUID, CORROSIVE, N.O.S.",
              "un_number": "1903"
            }
          },
          "ordered_quantity": 100,
          "ordered_total_volume_value": 43000,
          "packaging_type": {
            "code": "PYZ"
          }
        }
      ]
    }
  ],
  "container_number": "MSCU5285725",
  "container_scenario": "IMPORT",
  "container_type": {
    "code": "22G0"
  },
  "customer": {
    "code": "00083"
  },
  "customer_reference_number": "C2325995",
  "order_identifier": "ord-12332423",
  "teardown_input": [
    {
      "location": {
        "address": "Butaanweg 52-54",
        "city": "Rotterdam",
        "country": "NL",
        "name": "OCC Overbeek Cont. Control."
      }
    }
  ],
  "transport_service": {
    "name": "Container"
  }
}

Create a loaded container export transport order

This example shows how to create a transport that exports a loaded container. The setup section specifies the empty container pickup.

{
  "operation": "CREATE",
  "consignments": [
    {
      "delivery_stop": {
        "location": {
          "address": "Europaweg",
          "city": "Rotterdam",
          "country": "NL",
          "name": "APM terminals Maasvlakte II"
        },
        "reference_number": "3432423908987"
      },
      "pickup_stop": {
        "location": {
          "name": "Qargo Ghent office",
          "address": "Gaston Crommenlaan 4",
          "postal_code": "9050",
          "city": "Ghent",
          "country": "BE"
        },
        "reference_number": "3432441"
      },
      "goods": [
        {
          "absolute_max_temperature_value": "-8.0",
          "description": "Plastic buckets",
          "ordered_quantity": 1500,
          "packaging_type": {
            "code": "PE"
          }
        }
      ]
    }
  ],
  "container_number": "MSCU5285725",
  "container_scenario": "EXPORT",
  "container_type": {
    "code": "22RE"
  },
  "customer": {
    "code": "00007"
  },
  "customer_reference_number": "PUC-888315",
  "order_identifier": "d18f8309-0f26-4687-b32b-749008a0cb8e",
  "setup_input": [
    {
      "location": {
        "address": "Butaanweg 52-54",
        "city": "Rotterdam",
        "country": "NL",
        "name": "OCC Overbeek Cont. Control."
      }
    }
  ],
  "transport_service": {
    "name": "Container"
  }
}

Adding custom stops

In Qargo you can define custom stop actions. These stops can be added to configure additional stops related to the order.

These stops can be defined in the standalone_stops property.

Using standalone_stops to configure stops adds the following requirements to the order:

Every stop needs to have a unique positive integer assigned to it. This will determine the sequence of the stops in the order.
Every stops needs to have a custom_activity assigned to it. This will determine the type of stop that is being added to the order.

Example custom stops for an order

{
  "import_configuration": {
    "code": "API"
  },
  "transport_service": {
    "code": "YOUR_TRANSPORT_SERVICE_CODE"
  },
  "customer": {
    "code": "CUSTOMER_CODE"
  },
  "operation": "CREATE",
  "order_identifier": "EXT-ORDER-001",
  "customer_reference_number": "CUST-REF-001",
  "consignments": [
    {
      "pickup_stop": {
        "activity": "PICKUP",
        "date": "2026-04-01",
        "location": {
          "name": "Warehouse Antwerp",
          "address": "Kaai 100",
          "city": "Antwerp",
          "postal_code": "2000",
          "country": "BE"
        },
        "position": {
          "optimal": true,
          "position": 1
        }
      },
      "delivery_stop": {
        "activity": "DELIVERY",
        "date": "2026-04-01",
        "location": {
          "name": "Distribution Center Ghent",
          "address": "Industrieweg 50",
          "city": "Ghent",
          "postal_code": "9000",
          "country": "BE"
        },
        "position": {
          "optimal": true,
          "position": 3
        }
      },
      "standalone_stops": [
        {
          "activity": "CUSTOM",
          "custom_activity_label": "WEEG",
          "date": "2026-04-01",
          "location": {
            "name": "Weigh Station Mechelen",
            "address": "Weegbrug 1",
            "city": "Mechelen",
            "postal_code": "2800",
            "country": "BE"
          },
          "position": {
            "optimal": true,
            "position": 2
          }
        }
      ],
      "goods": [
        {
          "description": "Palletized goods",
          "quantity": 10,
          "package_type": "EURO_PALLET",
          "total_weight": 5000
        }
      ]
    }
  ]
}

Example custom stops for an container order

{
  "order_identifier": "QARGO_TEST_0005",
  "operation": "CREATE",
  "customer": {
    "name": "UPS SCS Coventry"
  },
  "setup_stops": [
    {
      "location": {
        "name": "Stop 1",
        "address": "Scheepzatestraat 1",
        "postal_code": "9000",
        "city": "Gent",
        "state": "Oost-Vlaanderen",
        "country": "BE"
      },
      "note": "Stop 1 notes",
      "date": "2024-08-20",
      "reference_number": "Stop 1 reference number",
      "planning_instructions": "Stop 1 instructions",
      "email": "info@qargo.com",
      "phone_number": "+0912341431",
      "mobile_number": "+324567890",
      "activity": "COLLECT_EMPTY_CONTAINER",
      "position": {
        "position": 1
      }
    }
  ],
  "consignments": [
    {
      "standalone_stops": [
        {
          "location": {
            "name": "Stop 2",
            "address": "Vlierstraat 4,",
            "postal_code": "9000",
            "city": "Gent",
            "state": "Oost-Vlaanderen",
            "country": "BE",
            "description": "HQ"
          },
          "note": "Stop 2 notes",
          "date": "2024-08-20",
          "reference_number": "Stop 2 number",
          "planning_instructions": "Stop 2 instructions",
          "email": "info@qargo.com",
          "phone_number": "+0912341431",
          "mobile_number": "+324567890",
          "custom_activity": "WEGEN",
          "position": {
            "position": 2
          }
        },
        {
          "location": {
            "name": "Stop 6",
            "address": "Vlierstraat 4,",
            "postal_code": "9000",
            "city": "Gent",
            "state": "Oost-Vlaanderen",
            "country": "BE",
            "description": "HQ"
          },
          "note": "Stop 6 notes",
          "date": "2024-08-20",
          "reference_number": "Stop 6 number",
          "planning_instructions": "Stop 6 instructions",
          "email": "info@qargo.com",
          "phone_number": "+0912341431",
          "mobile_number": "+324567890",
          "custom_activity": "WEGEN",
          "position": {
            "position": 6
          }
        },
        {
          "location": {
            "name": "Stop 3",
            "address": "Corbiestraat 4,",
            "postal_code": "9000",
            "city": "Gent",
            "state": "Oost-Vlaanderen",
            "country": "BE"
          },
          "note": "Stop 3 notes",
          "date": "2024-08-22",
          "reference_number": "Stop 3 reference number",
          "planning_instructions": "Stop 3 instructions",
          "email": "info@qargo.com",
          "phone_number": "+0912341431",
          "mobile_number": "+324567890",
          "custom_activity": "INKLAREN",
          "position": {
            "position": 3
          }
        }
      ],
      "pickup_stop": {
        "location": {
          "name": "Stop 4",
          "address": "Gaston Crommenlaan 4,",
          "postal_code": "9000",
          "city": "Gent",
          "state": "Oost-Vlaanderen",
          "country": "BE",
          "description": "HQ"
        },
        "note": "Stop 4 notes",
        "date": "2024-08-20",
        "reference_number": "Stop 4 reference number",
        "planning_instructions": "Stop 4 instructions",
        "email": "info@qargo.com",
        "phone_number": "+0912341431",
        "mobile_number": "+324567890",
        "activity": "PICKUP_EXPORT",
        "position": {
          "position": 4
        }
      },
      "delivery_stop": {
        "location": {
          "name": "Stop 5",
          "address": "Resedastraat 20",
          "postal_code": "9000",
          "city": "Gent",
          "state": "Oost-Vlaanderen",
          "country": "BE",
          "description": "Delivery"
        },
        "note": "Stop 5 notes",
        "date": "2024-08-21",
        "reference_number": "Stop 5 reference number",
        "planning_instructions": "Stop 5 instructions",
        "email": "info@qargo.com",
        "phone_number": "02123456",
        "mobile_number": "+329998888",
        "activity": "DELIVERY_EXPORT",
        "position": {
          "position": 5
        }
      }
    }
  ],
  "container": {
    "container_scenario": "EXPORT"
  },
  "customer_reference_number": "QARGO_TEST_0005",
  "transport_service": {
    "code": "CONTAINER_BOOKING"
  }
}

Examples

Basic order

{
  "order_identifier": "DEFAULT_ORDER",
  "operation": "CREATE",
  "customer": { "name": "Qargo" },
  "import_configuration": { "code": "API" },
  "consignments": [
    {
      "pickup_stop": {
        "location": {
          "name": "Qargo",
          "address": "Gaston Crommenlaan 4",
          "postal_code": "9000",
          "city": "Gent",
          "state": "Oost-Vlaanderen",
          "country": "BE",
          "description": "HQ"
        },
        "note": "Collection notes",
        "date": "2024-07-19",
        "reference_number": "",
        "planning_instructions": "",
        "email": "",
        "phone_number": "",
        "mobile_number": ""
      },
      "delivery_stop": {
        "location": {
          "name": "Qargo London",
          "address": "71-91 Aldwych",
          "postal_code": "WC2B 4HN",
          "city": "London",
          "country": "GB",
          "description": "Delivery"
        },
        "note": "Delivery notes",
        "date": "2024-07-19",
        "reference_number": "",
        "planning_instructions": "",
        "email": "",
        "phone_number": "",
        "mobile_number": ""
      },
      "goods": [{ "quantity": 1 }]
    }
  ],
  "customer_reference_number": "QARGO-123",
  "transport_service": { "code": "QARGO" },
  "service_level": { "code": "QARGO_NEXT_DAY" }
}

Container IMPORT scenario

{
  "order_identifier": "CONTAINER_IMPORT_ORDER",
  "operation": "CREATE",
  "customer": { "name": "QARGO" },
  "import_configuration": { "code": "API" },
  "teardown_stops": [
    {
      "location": {
        "name": "Ghent Container Yard",
        "address": "Scheepzatestraat 1",
        "postal_code": "9000",
        "city": "Gent",
        "state": "Oost-Vlaanderen",
        "country": "BE"
      },
      "note": "Empty container drop-off",
      "date": "2024-08-24",
      "reference_number": "",
      "planning_instructions": "",
      "email": "",
      "phone_number": "",
      "mobile_number": ""
    }
  ],
  "consignments": [
    {
      "pickup_stop": {
        "location": {
          "name": "Qargo Ghent",
          "address": "Gaston Crommenlaan 4,",
          "postal_code": "9000",
          "city": "Gent",
          "state": "Oost-Vlaanderen",
          "country": "BE",
          "description": ""
        },
        "note": "",
        "date": "2024-08-20",
        "reference_number": "",
        "planning_instructions": "",
        "email": "",
        "phone_number": "",
        "mobile_number": ""
      },
      "delivery_stop": {
        "location": {
          "name": "Qargo London",
          "address": "71-91 Aldwych",
          "postal_code": "WC2B 4HN",
          "city": "London",
          "country": "GB",
          "description": "Delivery"
        },
        "note": "Delivery notes",
        "date": "2024-08-22",
        "reference_number": "",
        "planning_instructions": "",
        "email": "",
        "phone_number": "",
        "mobile_number": ""
      }
    }
  ],
  "container": { "container_scenario": "IMPORT", "seal_number": "SEAL12345" },
  "customer_reference_number": "QARGO-01",
  "transport_service": { "code": "CONTAINER_TRANSPORT_SERVICE" }
}

Container EXPORT scenario

{
  "order_identifier": "CONTAINER_EXPORT_ORDER",
  "operation": "CREATE",
  "customer": { "name": "QARGO" },
  "import_configuration": { "code": "API" },
  "setup_stops": [
    {
      "location": {
        "name": "Ghent Container Yard",
        "address": "Scheepzatestraat 1",
        "postal_code": "9000",
        "city": "Gent",
        "state": "Oost-Vlaanderen",
        "country": "BE"
      },
      "note": "Empty container pickup location",
      "date": "2024-08-20",
      "reference_number": "",
      "planning_instructions": "",
      "email": "",
      "phone_number": "",
      "mobile_number": ""
    }
  ],
  "consignments": [
    {
      "pickup_stop": {
        "location": {
          "name": "Qargo Ghent",
          "address": "Gaston Crommenlaan 4,",
          "postal_code": "9000",
          "city": "Gent",
          "state": "Oost-Vlaanderen",
          "country": "BE",
          "description": ""
        },
        "note": "",
        "date": "2024-08-20",
        "reference_number": "",
        "planning_instructions": "",
        "email": "",
        "phone_number": "",
        "mobile_number": ""
      },
      "delivery_stop": {
        "location": {
          "name": "Qargo London",
          "address": "71-91 Aldwych",
          "postal_code": "WC2B 4HN",
          "city": "London",
          "country": "GB",
          "description": "Delivery"
        },
        "note": "Delivery notes",
        "date": "2024-08-22",
        "reference_number": "",
        "planning_instructions": "",
        "email": "",
        "phone_number": "",
        "mobile_number": ""
      }
    }
  ],
  "container": { "container_scenario": "EXPORT", "seal_number": "SEAL12345" },
  "customer_reference_number": "QARGO-00003",
  "transport_service": { "code": "CONTAINER_TRANSPORT_SERVICE" }
}

Order with multiple stops example

{
  "order_identifier": "MULTIPLE_STOPS_ORDER",
  "operation": "CREATE",
  "customer": { "name": "QARGO" },
  "consignments": [
    {
      "standalone_stops": [
        {
          "location": {
            "name": "Customs Ghent",
            "address": "Sint-Lievenslaan 27",
            "postal_code": "9000",
            "city": "Gent",
            "state": "Oost-Vlaanderen",
            "country": "BE",
            "description": "Customs office location"
          },
          "note": "",
          "date": "2024-08-20",
          "reference_number": "",
          "planning_instructions": "",
          "email": "",
          "phone_number": "",
          "mobile_number": "",
          "custom_activity": "CUSTOMS",
          "position": { "position": 1 }
        },
        {
          "location": {
            "name": "Truck weight station",
            "address": "Belgicastraat 10",
            "postal_code": "9000",
            "city": "Gent",
            "state": "Oost-Vlaanderen",
            "country": "BE",
            "description": "HQ"
          },
          "note": "",
          "date": "2024-08-20",
          "reference_number": "",
          "planning_instructions": "",
          "email": "",
          "phone_number": "",
          "mobile_number": "",
          "custom_activity": "WEIGHT_STATION",
          "position": { "position": 2 }
        },
        {
          "location": {
            "name": "Truckwash Ghent",
            "address": "Traktaatweg 23",
            "postal_code": "9000",
            "city": "Gent",
            "state": "Oost-Vlaanderen",
            "country": "BE"
          },
          "note": "",
          "date": "2024-08-23",
          "reference_number": "",
          "planning_instructions": "",
          "email": "",
          "phone_number": "",
          "mobile_number": "",
          "custom_activity": "WASHING",
          "position": { "position": 5 }
        }
      ],
      "pickup_stop": {
        "location": {
          "name": "Qargo Ghent",
          "address": "Gaston Crommenlaan 4,",
          "postal_code": "9000",
          "city": "Gent",
          "state": "Oost-Vlaanderen",
          "country": "BE",
          "description": ""
        },
        "note": "",
        "date": "2024-08-20",
        "reference_number": "",
        "planning_instructions": "",
        "email": "",
        "phone_number": "",
        "mobile_number": "",
        "activity": "PICKUP",
        "position": { "position": 3 }
      },
      "delivery_stop": {
        "location": {
          "name": "Qargo London",
          "address": "71-91 Aldwych",
          "postal_code": "WC2B 4HN",
          "city": "London",
          "country": "GB",
          "description": "Delivery"
        },
        "note": "Delivery notes",
        "date": "2024-08-22",
        "reference_number": "",
        "planning_instructions": "",
        "email": "",
        "phone_number": "",
        "mobile_number": "",
        "activity": "DELIVERY",
        "position": { "position": 4 }
      }
    }
  ],
  "customer_reference_number": "QARGO_001",
  "transport_service": { "code": "FULL_LOADS" }
}

Order with ADR goods

technical_name_by_locale is writable; use it to provide localized technical names for the dangerous goods. Each key must be a supported locale code, and each value is the technical name for that locale. adr_name_by_locale is read-only; the API generates this field automatically and ignores any submitted value. The example below provides technical names for four locales.

{
  "order_identifier": "DANGEROUS_GOODS_ORDER",
  "operation": "CREATE",
  "customer": { "name": "QARGO" },
  "import_configuration": { "code": "API" },
  "consignments": [
    {
      "pickup_stop": {
        "location": {
          "name": "Qargo Ghent",
          "address": "Gaston Crommenlaan 4,",
          "postal_code": "9000",
          "city": "Gent",
          "state": "Oost-Vlaanderen",
          "country": "BE",
          "description": ""
        },
        "note": "",
        "date": "2024-08-20",
        "reference_number": "",
        "planning_instructions": "",
        "email": "",
        "phone_number": "",
        "mobile_number": ""
      },
      "delivery_stop": {
        "location": {
          "name": "Qargo London",
          "address": "71-91 Aldwych",
          "postal_code": "WC2B 4HN",
          "city": "London",
          "country": "GB",
          "description": "Delivery"
        },
        "note": "Delivery notes",
        "date": "2024-08-22",
        "reference_number": "",
        "planning_instructions": "",
        "email": "",
        "phone_number": "",
        "mobile_number": ""
      },
      "goods": [
        {
          "packaged_items": [
            {
              "adr": {
                "un_number": "1956",
                "packaging_type": "BOX",
                "emergency_phone_number": "+32456789010",
                "technical_name_by_locale": {
                  "de-DE": "NEG Stoffname",
                  "en": "NEG Substance name",
                  "fr-FR": "NEG Nom de la substance",
                  "nl-BE": "NEG Stofnaam"
                }
              },
              "quantity": 5,
              "total_volume_l": 100,
              "total_weight_kg": 100,
              "description": "Dangerous and flammable goods"
            }
          ],
          "description": "Fuel",
          "quantity": 1,
          "product_name": "FUEL"
        }
      ]
    }
  ],
  "customer_reference_number": "QARGO-001",
  "transport_service": { "code": "HAZARDOUS" },
  "service_level": { "code": "NEXT_DAY" }
}

Order with pallets and custom barcodes

{
  "order_identifier": "PALLETS_WITH_BARCODES_ORDER",
  "operation": "CREATE",
  "customer": { "name": "QARGO" },
  "import_configuration": { "code": "API" },
  "consignments": [
    {
      "pickup_stop": {
        "location": {
          "name": "Qargo Ghent",
          "address": "Gaston Crommenlaan 4,",
          "postal_code": "9000",
          "city": "Gent",
          "state": "Oost-Vlaanderen",
          "country": "BE",
          "description": ""
        },
        "note": "",
        "date": "2024-08-20",
        "reference_number": "",
        "planning_instructions": "",
        "email": "",
        "phone_number": "",
        "mobile_number": ""
      },
      "delivery_stop": {
        "location": {
          "name": "Qargo London",
          "address": "71-91 Aldwych",
          "postal_code": "WC2B 4HN",
          "city": "London",
          "country": "GB",
          "description": "Delivery"
        },
        "note": "Delivery notes",
        "date": "2024-08-22",
        "reference_number": "",
        "planning_instructions": "",
        "email": "",
        "phone_number": "",
        "mobile_number": ""
      },
      "goods": [
        {
          "quantity": 1,
          "packaging_type": {
            "name": "Full Pallet",
            "packaging_size": { "code": "FP" }
          },
          "handling_units": [
            { "barcode": { "value": "01J93R8V517R7133FVCM3ZCJNN" } }
          ]
        },
        {
          "quantity": 2,
          "packaging_type": {
            "name": "Half Pallet",
            "packaging_size": { "code": "HP" }
          },
          "handling_units": [
            { "barcode": { "value": "01J93R9024CNTJJPQG8WDP2PVX" } },
            { "barcode": { "value": "01J93R9PKY3A5C9S6T4VV12C8B" } }
          ]
        }
      ]
    }
  ],
  "customer_reference_number": "QARGO-0001",
  "transport_service": { "code": "PALLETS" },
  "service_level": { "code": "PREMIUM_NEXT_DAY" }
}

Changelog

Recent additions and changes to the API, newest first.

2026-09-04

Outgoing data

Added: Goods in outbound order payloads — operational visibility, fleet and subcontractor dispatch, intermodal and location bookings — gain an optional hs_codes object, carrying count: the number of HS codes for the good. The field is omitted when not set on the good.
- Affects: Customer portal, Fleet dispatch, Intermodal, Location booking, Order, Subcontractor dispatch, Visibility

2026-08-19

API

Added: PaymentTermCode gains END_OF_MONTH_0_NET_20, for a payment term of end of this month plus 20 days.
- Affects: Accounting, Company, Order, Task, Trip

2026-08-14

API

Fixed: The /me response now includes active_tenant_slug for CUSTOMER-role tokens, matching other API roles.
- Affects: System
- Endpoints: GET /me

2026-08-12

API

Changed: Charge status now reports INVOICE_POSTED for charges on a posted invoice and DO_NOT_INVOICE for charges excluded from invoicing. These were previously reported as CREATED, including on existing charges, so invoiced and uninvoiced charges can now be told apart. Treat the status as an open set and map unrecognised values to CREATED.
- Affects: Order, Customer portal
- Endpoints: GET /v1/orders/order/{order_id}/charges, POST /v1/orders/order/{order_id}/charges/approval

2026-08-11

Outgoing data

Added: VisibilityOrderStatus in operational visibility payloads gains BLOCKED, for an order that is blocked or on hold. Treat the order status as an open set and ignore values you do not recognise rather than rejecting the event.
- Affects: Customer portal, Order, Visibility

2026-08-05

Outgoing data

Added: ResourceType in operational visibility payloads gains HANDLING, for handling equipment such as a forklift assigned to a stop, and SUBCONTRACTOR, which the payload has been able to carry for some time but was undocumented. Treat the resource type as an open set and ignore values you do not recognise rather than rejecting the event.
- Affects: Customer portal, Order, Visibility

2026-07-29

Outgoing data

Changed: location.name is no longer guaranteed in operational visibility payloads. A location without a name, such as an address-only one created automatically by an order import, previously blocked the entire visibility event from being sent; it is now sent with name omitted. Treat the field as optional and fall back to address and city when it is absent.
- Affects: Customer portal, Order, Visibility

2026-07-23

API

Fixed: Updating a resource no longer returns a server error when note or external_id is omitted; the value is now stored as an empty string, matching create. Sending an explicit null for note, external_id, name, or locale is now rejected with a validation error (422) instead of failing with a server error on update, or being silently ignored on create.
- Affects: Resource
- Endpoints: POST /v1/resources/resource, PUT /v1/resources/resource/{resource_id}, PATCH /v1/resources/resource/{resource_id}
Added: Stops in order status responses now include stop_type, identifying the consignment pickup (PICKUP) and delivery (DELIVERY) stops. The field is empty for other stops.
- Affects: Order
- Endpoints: GET /v1/orders/order/{order_id}/status

Outgoing data

Added: Resources in visibility events can now report the BARGE and AIRPLANE types.
- Affects: Customer portal, Order, Visibility

2026-07-22

API

Removed: Order status responses no longer include first_pickup_stop. The same information can be derived from the stops array, which is ordered by stop sequence: the first stop with a pickup activity_label is the first pickup stop, and likewise the last stop with a delivery activity_label is the last delivery stop.
- Affects: Order
- Endpoints: GET /v1/orders/order/{order_id}/status

2026-07-10

API

Added: Order status responses now include first_pickup_stop.
- Affects: Order
- Endpoints: GET /v1/orders/order/{order_id}/status
Changed: last_delivery_stop now uses the documented order-status stop shape.
- Affects: Order
- Endpoints: GET /v1/orders/order/{order_id}/status

2026-07-06

API

Changed: Validation error responses now return an errors array instead of the flat detail, field and path fields. Each item is a ValidationErrorDetail with message, field, path and detail; the array is always present and non-empty, so a single failure is a one-item array and integrators can handle one and many failures the same way.
- Affects: Accounting, Authentication, Company, Document, Order, Resource, Task, Trip

2026-06-03

Outgoing data

Added: Operational order visibility now includes goods information.
- Affects: Customer portal, Order, Visibility

2026-03-10

Outgoing data

Added: Operational order visibility now includes stop ETA times (eta_start_time, eta_end_time).
- Affects: Customer portal, Order, Visibility

2026-01-09

Outgoing data

Added: Operational order visibility now includes the customer id.
- Affects: Customer portal, Order, Visibility

Download OpenAPI description

docs.json

docs.yaml

Languages

Servers

https://api.qargo.com