{"templateId":"openapi_docs","sharedDataIds":{"openAPIDocsStore":"oas-docs.json","sidebar":"sidebar-sidebars.yaml"},"props":{"definitionId":"docs.json","dynamicMarkdocComponents":[],"baseSlug":"/docs","seo":{"title":"Qargo TMS API"},"itemId":"","disableAutoScroll":true,"metadata":{"type":"openapi","title":"Qargo TMS API","description":"For support, please contact integrations@qargo.com.\n# Overview\n\n
\n

Tenant API Documentation

\n

You are currently viewing the Tenant API Documentation. This API provides access to tenant-level integrations and operational endpoints.

\n
\n\n
\n\n### Documentation for Other Parties\n\n
\n\n
\n

Subcontractor API

\n

Fleet dispatch and subcontractor-specific endpoints for transportation management.

\n
\n Subcontractor Documentation\n
\n
\n\n
\n

Customer API

\n

Customer portal endpoints for order tracking, status monitoring, and customer-facing operations.

\n
\n Customer Documentation\n
\n
\n\n
\n\n# Authentication\n\nThe api requires oauth2 authentication with client id/secret. This should only be used for service to service communication.\n\n## Creating application credentials\n\nApplication client credentials can be created by users with the `Super admin` role in the Qargo application.\nUsers can create and remove application clients by navigating to Configuration -> Organisation Settings (API clients sections).\n\nApplications need to be linked to a valid integration id, identifying the Qargo approved integrator.\nPlease contact [us](mailto:integrations@qargo.com) if you don't have an id yet.\n\n## Obtaining an access token\n\nTo 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.\n\nThe [/auth/token endpoint](/docs/section/authentication/the-api-call-to-request-tokens) can be used to generate an access token (JWT):\n\nThis token will need to be refreshed after expiration (we provide the 'expires_in' in the token response to check validity).\n\n### Understanding Basic Authentication\n\nBasic 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:\n\n- **Format**: `Authorization: Basic `\n- **Credentials Encoding**: The client ID and secret are concatenated with a colon (e.g., `client_id:secret_id`) and then Base64-encoded.\n\n### The API Call to Request Tokens\n\nThe `/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`.\n\n#### Request Details\n\n- **Method**: POST\n- **URL**: `https://api.qargo.com/v1/auth/token`\n- **Headers**:\n - `Content-Type: application/json`\n - `Authorization: Basic `\n- **Body**: Empty.\n- **Parameters**: None.\n\nExample using `curl`:\n\n```\ncurl -XPOST https://api.qargo.com/v1/auth/token -H 'Content-type: application/json' -u ''\n```\n\n## Webhook authentication\n\n> **Important:** Webhook endpoints use a **different authentication method** than regular API endpoints. Do not use OAuth tokens for webhooks.\n\nQargo webhooks, such as those for order import and status updates, use **Basic Authentication** instead of OAuth. See [Understanding Basic Authentication](#understanding-basic-authentication) for details on the Basic Auth scheme.\n\nWebhook credentials (client id and secret id) are **provisioned by Qargo** when your webhook integration is configured — contact [integrations@qargo.com](mailto:integrations@qargo.com) to obtain them. They are **separate from your API credentials** and must be used exclusively for webhook endpoints.\n\n### API vs Webhook authentication summary\n\n| | **API endpoints** | **Webhook endpoints** |\n|---|---|---|\n| **Auth method** | OAuth2 (Client Credentials) | Basic Authentication |\n| **Credentials** | API client_id + secret_id → Bearer JWT token | Webhook client_id + secret_id (directly in header) |\n| **Header format** | `Authorization: Bearer ` | `Authorization: Basic ` |\n| **Where to find credentials** | Configuration → Organisation Settings → API clients | Provisioned by Qargo — contact [integrations@qargo.com](mailto:integrations@qargo.com) |\n| **Token refresh needed?** | Yes (JWT expires) | No (credentials sent with each request) |\n\n### Common mistake\n\nWebhook 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.\n\n### Example webhook request\n\n```\ncurl -XPOST https://api.qargo.com/v1/webhook/order-import \\\n -H 'Content-Type: application/json' \\\n -u ':' \\\n -d '{ ... }'\n```\n\n# Rate Limits\n\nTo maintain API stability and prevent abuse, we enforce rate limits on a per-tenant basis.\n\n### Limits\n\nThe 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.\n\n| **Category** | **Scope** | **Limit** |\n| --- | --- | --- |\n| Authentication | `/auth/token` | 5 requests per hour |\n| General API Usage | All endpoints *except* authentication and webhooks | 2 requests per second (sustained); up to 3 per second (bursts) |\n\n### Enforcement\n\nRate 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.\n\nExample response:\n```http\nHTTP/1.1 429 Too Many Requests\nContent-Type: application/json\nRetry-After: 58\n\n{\"error\":\"Rate limit exceeded\"}\n```\n\nApplications must handle this response correctly by respecting the `Retry-After` header and retrying after the specified delay, regardless of whether the request appeared to be within the estimated limits.\n\nFor any concerns about these limits, please contact us at [integrations@qargo.com](mailto:integrations@qargo.com).\n\n# API Best Practices\n\nThis section outlines recommended practices for efficiently working with the Qargo API.\n\n## Pagination\n\nSome list endpoints support pagination. This means the endpoint offers a `next_cursor` in the response payload and accepts a `cursor` as query parameter. If pagination is supported and their response contains a `next_cursor` property, then you can use the `cursor` as a query parameter in a subsequent request to fetch the next page of results. Using query parameters is mutually exclusive with using the cursor.\n\n
\n\n### How Pagination Works\n\n1. **Initial Request**: Make a request to a paginated endpoint without any cursor parameter\n2. **Check Response**: If the response includes a `next_cursor` field, more data is available\n3. **Subsequent Requests**: Use the `next_cursor` value as the `cursor` parameter in your next request\n4. **Continue**: Repeat until no `next_cursor` is returned\n\n
\n\n### Example Usage\n\n```http\nGET /api/v1/orders\n```\n\nResponse:\n```json\n{\n \"data\": [...],\n \"next_cursor\": \"eyJpZCI6MTIzfQ==\"\n}\n```\n\nNext request:\n```http\nGET /api/v1/orders?cursor=eyJpZCI6MTIzfQ==\n```\n
\n\n### Recommendations\n\n- Always check for the presence of `next_cursor` before making additional requests\n- Store cursor values temporarily; they may expire after a certain period\n- Avoid using other query parameters when using cursor-based pagination\n\n## Backward compatibility\n\nThe Qargo API follows these backward compatibility principles:\n\n- **New fields may be added** to response payloads at any time. Adding new fields is **not** considered a breaking change.\n- **Integrators should ignore unknown fields** when parsing responses. Do not fail on unexpected properties.\n- **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.\n- **Existing fields will not be renamed or removed** without prior notice and a deprecation period.\n\n## Date and time formats\n\nAll date and time fields in the API follow ISO 8601:\n\n| Type | Format | Example | Description |\n|------|--------|---------|-------------|\n| Date | `YYYY-MM-DD` | `2024-12-31` | Calendar date without time component |\n| Datetime | `YYYY-MM-DDTHH:mm:ssZ` | `2024-12-31T14:30:00Z` | Timestamp in UTC (indicated by `Z` suffix) |\n| Time | `HH:mm` | `09:30` | Time of day in 24-hour format |\n\n- **Datetime fields are always in UTC.** Convert to local time on the client side.\n- **Date fields have no timezone.** They represent a calendar date (e.g. a planned delivery date).\n- **Time fields** are used for time windows (e.g. delivery windows) and are in 24-hour format without seconds.\n\n# Concepts\n\n## Company\n\nA company in Qargo can be both a customer as well as a subcontractor (supplier).\nThe entity will have a single id within Qargo. The api client can link companies by this id,\nor by the accounting code, which is a user defined code field.\n\n## Order\n\nTransport order to execute. Also called job in other TMS systems. It contains all transport details:\n\n- Order references\n- Customer [company](/docs/section/concepts/company)\n- Consigments, with their [stop](/docs/section/concepts/stop) locations, time windows, references\n- Definition of the goods to transport\n\n## Stop\n\n- A stop is a part of a transport, at a certain date, optional timeslot and location.\n In addition to the planned times, it also tracks the actual times for a completed stop.\n Stops can be linked to [orders](/docs/section/concepts/order), or can be defined standalone (for example a cleaning stop).\n All stops are linked to a Trip.\n\n### Stop group\n\nStops can be grouped together according to their activity and location. This is called a stop group.\n\n## Trip\n\nA trip contains [stops](/docs/section/concepts/stop) from various [orders](/docs/section/concepts/order), or standalone [stops](/docs/section/concepts/stop). It tracks how a certain\ntransport is planned, and who will execute that transport.\n\n## Task\n\nA task is the primary workflow concept in Qargo. Users can define their own flow,\nusing both built-in tasks as well a custom defined ones. For the current accounting use case,\nwe only expose the `post invoice/credit note` task, that allows users to send invoices to an accounting system.\n\n## Resource\n\nA resource in Qargo is a vehicle, driver, trailer or other entity that can be assigned to a [trip](/docs/section/concepts/trip).\n\n## Unavailability\n\nAn unavailability indicates that a specific [resource](/docs/section/concepts/resource) is not available for use for a given time range. An unavailability has a reason to indicate why the resource is not available.\n\n## Status update\n\nA status update reflects a status change in an entity.\n\n## Document\n\nA 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).\n\n# Postman collection\n\nWe have a [postman](https://www.postman.com/downloads/) collection [available](/docs/postman.json \"download\")\nwith interactive examples (right click to download). Download this to a local folder, and import it into Postman for usage.\n\n### Instructions\n\n- Make sure you have a Postman client available. This can either be a local installed version or the web based version.\n- Request credentials for the Qargo API for order creation\n- Download and import the collection\n- Set the collection variables username and password with the credentials received\n- Execute the Request Access token request in the Authentication folder. You have now a valid access key for 1 hour. If you get the error message that the key is no longer valid, please refresh the access key by invoking this endpoint again.\n- You can now explore the different order endpoints\n\n# Functionality\n\nThe api exposes the following functionality:\n\n- Order management: create/update and get the status of transport orders.\n- Retrieve trip information: retrieve information about Qargo [trips](/docs/section/concepts/trip).\n- Visibility: send events to an external system using webhooks.\n- Order dispatch: send transport orders to a 3rd party using webhooks.\n- Accounting: interface an accounting system using the api endpoints.\n- Documents: interface to download documents\n\n## Order management\n\nAvailable functionality:\n\n- Create [orders](/docs/section/concepts/order) in Qargo and track order status.\n- Export any existing order to be used as a template for future order creation.\n\nThe api reference is available here: [order api](/docs/api-order).\n\n## Trip information\n\n[Trips](/docs/section/concepts/trip) can't be manipulated yet through the api, but it is possible to retrieve trip information.\nWe currently have an endpoint available to retrieve the charge information for a certain endpoint.\n\nYou can update the status of [stops](/docs/section/concepts/stop) and [stop groups](/docs/section/concepts/stop) of a trip using a [webhook](/docs/webhooks-inbound/subcontractor-status-update-webhook).\n\n## Resource management\n\n### Resource\n\n[Resources](/docs/section/concepts/resource) this should be used together with the endpoints to fetch unavailabilities as a resource unavailability is linked to a resource.\n\n### Unavailability\n\n[Resource unavailabilities](/docs/section/concepts/unavailability) can be managed through the API. The following operations are supported:\n\n- Creating an unavailability for a resource\n- Updating an unavailability for a resource\n- Deleting an unavailability for a resource\n- Fetching an unavailability for a resource\n- Fetching all unavailabilities for a resource\n\nThe goal of these endpoints is to allow external systems to manage the availability of resources in Qargo. An `external_id` is stored alongside the unavailability to allow for easy linking between the external system and Qargo. This `external_id` should be provided if a referential link is needed between the external system and Qargo.\n\nSee the [examples](/docs/section/resources/unavailabilities) on how to use the unavailability endpoints.\n\n## Visibility\n\nWe support visibility (sending messages triggered by Qargo system events) in the api as well.\nThese messages can be send out as a [webhook](/docs/webhooks-outbound/operational_visibility_event_webhook_post), or an EDI connection.\n\nFor most endpoints, visibility only trigger on status changes (for example, from stop `IN_PROGRESS` -> `COMPLETED`).\nThere are a few exceptions, these will be indicated in the overview:\n\n- Order level\n - We send out a visibility event on `ACCEPTED` (order created), `REJECTED` (order skipped) and `COMPLETED` (all stops for order completed).\n- Stop level\n - We send out a visibility event on `AT_STOP` (arrived at stop), `COMPLETED` (all activities completed for stop).\n- Position level (note: for every telematics update)\n- Trip level\n - We send a visibility event when a trip changes to `PLANNED` and when it transitions to `COMPLETED`.\n- Resource level\n - We send an event when a resource is assigned to a certain [trip](/docs/section/concepts/trip).\n\n## Order dispatch\n\nIt is also possible to subcontract trips to other parties. This is possible using two push endpoints:\n\n- Outgoing dispatched trip [payload](/docs/webhooks-outbound/subcontractor-dispatch-payload).\n- Incoming [message format](/docs/webhooks-inbound/subcontractor-status-update-webhook) to update subcontracted status.\n\n\n## Documents\n\nWe offer an interface to download documents. The documents can be fetched using the [document endpoints](/docs/api-document).\n\n## Request additional endpoints\n\nPlease contact [us](mailto:integrations@qargo.com) for inqueries regarding additional api functionality.\n\n# Transport order creation & status\n\nThis sections details how to construct payloads to create transport orders using the order upload endpoint([/orders/order/upload](/docs/api-order/import_order_v1_orders_order_upload_post)).\n\n## Order creation metadata\n\nOrders 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.\n\n```json\n{\n \"upload_id\": \"\",\n \"upload_status\": \"IN_PROGRESS\",\n \"upload_url\": \"v1/orders/order/upload/\",\n \"order_id\": null,\n \"order_url\": null\n}\n```\n\nYou need to store the `upload_id` so you can fetch the status of the order creation by calling `GET /orders/order/upload/`\n\nBased 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.\n\n**Example payload `GET /orders/order/upload/e01b3db1-4e49-4241-a91e-7534da884d46`** with a created order\n\n```json\n{\n \"upload_id\": \"e01b3db1-4e49-4241-a91e-7534da884d46\",\n \"upload_status\": \"COMPLETED\",\n \"upload_url\": \"v1/orders/order/upload/e01b3db1-4e49-4241-a91e-7534da884d46\",\n \"order_id\": \"a2a84715-0027-49af-ad30-494c0ccf75cc\",\n \"order_url\": \"v1/orders/order/a2a84715-0027-49af-ad30-494c0ccf75cc\"\n}\n```\n\n## Order identifier\n\nThe `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.\n\nThe `order_identifier` main usage is for `deduplication`, you cannot use the `order_identifier` to fetch an order.\n\n## Create an order\n\nThe first example is a simple transport from our london office to our Ghent office.\nPlease note that the transport service will need to be matched with the one in your system.\n\n```json\n{\n \"operation\": \"CREATE\",\n \"consignments\": [\n {\n \"delivery_stop\": {\n \"date\": \"2022-05-03\",\n \"location\": {\n \"name\": \"Qargo Ghent office\",\n \"address\": \"Gaston Crommenlaan 4\",\n \"postal_code\": \"9050\",\n \"city\": \"Ghent\",\n \"country\": \"BE\"\n },\n \"reference_number\": \"D12345\"\n },\n \"pickup_stop\": {\n \"date\": \"2022-04-21\",\n \"location\": {\n \"name\": \"Qargo London office\",\n \"address\": \"71-91 Aldwych\",\n \"postal_code\": \"WC2B 4HN\",\n \"city\": \"London\",\n \"country\": \"UK\"\n },\n \"reference_number\": \"P123456\"\n }\n }\n ],\n \"customer_reference_number\": \"T12345\",\n \"customer\": {\n \"code\": \"00020\"\n },\n \"order_identifier\": \"T1234393\",\n \"transport_service\": {\n \"name\": \"General\"\n }\n}\n```\n\nNote: it is possible to 'export' existing orders in the api to use as examples/templates.\nSee the [Export existing orders](/docs/section/transport-order-creation-and-status/export-an-existing-order) section.\n\n## Update an order\n\nThe following order is an update of an existing order. Note the `UPDATE` value of the operation field.\n\nImportant remarks:\n\n- Not all the fields of the order can be updated\n- the `order_identifier` field is used to identify the order to update\n\n**Example of an order update**\n\n```json\n{\n \"order_identifier\": \"QARGO_TEST_0001\",\n \"operation\": \"UPDATE\",\n \"customer\": {\n \"name\": \"UPS SCS Coventry\"\n },\n \"consignments\": [\n {\n \"pickup_stop\": {\n \"location\": {\n \"name\": \"Qargo HQ\",\n \"address\": \"Gaston Crommenlaan 4,\",\n \"postal_code\": \"9000\",\n \"city\": \"Gent\",\n \"state\": \"Oost-Vlaanderen\",\n \"country\": \"BE\",\n \"description\": \"Qargo HQ building\"\n },\n \"note\": \"Pickup 4 boxes of pasta\",\n \"date\": \"2024-08-20\",\n \"reference_number\": \"QACOLLI001\",\n \"planning_instructions\": \"If closed, call mobile number\",\n \"email\": \"info@qargo.com\",\n \"phone_number\": \"+0912341431\",\n \"mobile_number\": \"+324567890\"\n },\n \"delivery_stop\": {\n \"location\": {\n \"name\": \"Grocery store\",\n \"address\": \"Resedastraat 20\",\n \"postal_code\": \"9000\",\n \"city\": \"Gent\",\n \"state\": \"Oost-Vlaanderen\",\n \"country\": \"BE\",\n \"description\": \"Grocery store\"\n },\n \"note\": \"Don't forget to sign the documents\",\n \"date\": \"2024-08-21\",\n \"reference_number\": \"QADELIV001\",\n \"planning_instructions\": \"Alarm code: 123456\",\n \"email\": \"info@qargo.com\",\n \"phone_number\": \"02123456\",\n \"mobile_number\": \"+329998888\"\n },\n \"goods\": [\n {\n \"description\": \"4 boxes of pasta\",\n \"quantity\": 4\n }\n ]\n }\n ],\n \"customer_reference_number\": \"QARGO_TEST_0001\",\n \"transport_service\": {\n \"code\": \"CONTAINER_BOOKING\"\n }\n}\n```\n\n## Cancel an order\n\nTo 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.\n\nA 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.\n\n```json\n{\n \"operation\": \"DELETE\",\n \"consignments\": [\n {\n \"delivery_stop\": {\n \"date\": \"2022-05-03\",\n \"location\": {\n \"name\": \"Qargo Ghent office\",\n \"address\": \"Gaston Crommenlaan 4\",\n \"postal_code\": \"9050\",\n \"city\": \"Ghent\",\n \"country\": \"BE\"\n },\n \"reference_number\": \"D12345\"\n },\n \"pickup_stop\": {\n \"date\": \"2022-04-21\",\n \"location\": {\n \"name\": \"Qargo London office\",\n \"address\": \"71-91 Aldwych\",\n \"postal_code\": \"WC2B 4HN\",\n \"city\": \"London\",\n \"country\": \"UK\"\n },\n \"reference_number\": \"P123456\"\n }\n }\n ],\n \"customer_reference_number\": \"T12345\",\n \"customer\": {\n \"code\": \"00020\"\n },\n \"order_identifier\": \"T1234393\",\n \"transport_service\": {\n \"name\": \"General\"\n }\n}\n```\n\n## Export an existing order\n\nIt is possible to export a manually created order in the api. We first need to determine the technical id of this order.\n\n![Retrieve order id](/docs/static/order_id.png).\n\nThe order can be exported with the following endpoint:\n[Export order](/docs/section/transport-order-creation-and-status/export-an-existing-order).\nThe output of this endpoint corresponds to the order creation format. Just make sure to use a different [`order_identifier`](/docs/section/transport-order-creation-and-status/order-identifier), otherwise the 'new' order will be interpreted as an update.\n\n\n## Fetch order data and status\n\nWith the `GET /orders/order/` [endpoint](/docs/api-order/get_order_details_v1_orders_order__order_id__get), you can fetch the data related to the order. This contains the current `status` of the order along with other data.\n\n## Container orders\n\nThere are 2 types of container orders that can be created using the API, `IMPORT` and `EXPORT`.\n\n### Import\n\nThis scenario contains of 2 main stops additional optional stops.\n\n1. Pickup of a loaded container\n2. Unload container\n3. Drop off empty container (Optional, configured in `teardown_stops`)\n\nThe `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\n\n**Example `IMPORT` container scenario**\n\n```json\n{\n \"order_identifier\": \"QARGO_TEST_0002\",\n \"operation\": \"CREATE\",\n \"customer\": {\n \"name\": \"UPS SCS Coventry\"\n },\n \"teardown_stops\": [\n {\n \"location\": {\n \"name\": \"Container yard\",\n \"address\": \"Scheepzatestraat 1\",\n \"postal_code\": \"9000\",\n \"city\": \"Gent\",\n \"state\": \"Oost-Vlaanderen\",\n \"country\": \"BE\"\n },\n \"note\": \"Drop off the container on the designated location\",\n \"date\": \"2024-08-20\",\n \"reference_number\": \"CONT0001\",\n \"planning_instructions\": \"Put next to the red container\",\n \"email\": \"info@qargo.com\",\n \"phone_number\": \"+0912341431\",\n \"mobile_number\": \"+324567890\"\n }\n ],\n \"consignments\": [\n {\n \"pickup_stop\": {\n \"location\": {\n \"name\": \"Container pickup location\",\n \"address\": \"Gaston Crommenlaan 4,\",\n \"postal_code\": \"9000\",\n \"city\": \"Gent\",\n \"state\": \"Oost-Vlaanderen\",\n \"country\": \"BE\",\n \"description\": \"This is the container pickup location\"\n },\n \"note\": \"Pick up the green container\",\n \"date\": \"2024-08-20\",\n \"reference_number\": \"CONT0002\",\n \"planning_instructions\": \"Code of the container is 1234\",\n \"email\": \"info@qargo.com\",\n \"phone_number\": \"+0912341431\",\n \"mobile_number\": \"+324567890\"\n },\n \"delivery_stop\": {\n \"location\": {\n \"name\": \"Sports store\",\n \"address\": \"Resedastraat 20\",\n \"postal_code\": \"9000\",\n \"city\": \"Gent\",\n \"state\": \"Oost-Vlaanderen\",\n \"country\": \"BE\",\n \"description\": \"This is the delivery location of the container goods\"\n },\n \"note\": \"1000 boxes of shoes\",\n \"date\": \"2024-08-21\",\n \"reference_number\": \"CONT0003\",\n \"planning_instructions\": \"Use mobile number if gate is closed\",\n \"email\": \"info@qargo.com\",\n \"phone_number\": \"02123456\",\n \"mobile_number\": \"+329998888\"\n }\n }\n ],\n \"container\": {\n \"container_scenario\": \"IMPORT\"\n },\n \"customer_reference_number\": \"QARGO_TEST_0002\",\n \"transport_service\": {\n \"code\": \"CONTAINERS\"\n }\n}\n```\n\n### Export\n\nThis scenario contains 2 main stops with additional optional stops:\n\n1. Pickup empty container (Optional, configured in `setup_stops`)\n2. Load empty container\n3. Drop off loaded container\n\nThe `container_scenario` is set as `EXPORT` and the `setup_stops` property allows to define additional optional stops.\n\n**Example of an `EXPORT` `container_scenario`**\n\n```json\n{\n \"order_identifier\": \"QARGO_TEST_0003\",\n \"operation\": \"CREATE\",\n \"customer\": {\n \"name\": \"UPS SCS Coventry\"\n },\n \"setup_stops\": [\n {\n \"location\": {\n \"name\": \"Container yard\",\n \"address\": \"Scheepzatestraat 1\",\n \"postal_code\": \"9000\",\n \"city\": \"Gent\",\n \"state\": \"Oost-Vlaanderen\",\n \"country\": \"BE\"\n },\n \"note\": \"Pickup empty container on the designated location\",\n \"date\": \"2024-08-20\",\n \"reference_number\": \"CONT0001\",\n \"planning_instructions\": \"Blue container, next to the red container\",\n \"email\": \"info@qargo.com\",\n \"phone_number\": \"+0912341431\",\n \"mobile_number\": \"+324567890\"\n }\n ],\n \"consignments\": [\n {\n \"pickup_stop\": {\n \"location\": {\n \"name\": \"Container loading location\",\n \"address\": \"Gaston Crommenlaan 4,\",\n \"postal_code\": \"9000\",\n \"city\": \"Gent\",\n \"state\": \"Oost-Vlaanderen\",\n \"country\": \"BE\",\n \"description\": \"Qargo HQ, has a container loading bay\"\n },\n \"note\": \"Fill with 1000 boxes of Qargo shirts\",\n \"date\": \"2024-08-20\",\n \"reference_number\": \"CONT0002\",\n \"planning_instructions\": \"Code of the container is 1234\",\n \"email\": \"info@qargo.com\",\n \"phone_number\": \"+0912341431\",\n \"mobile_number\": \"+324567890\"\n },\n \"delivery_stop\": {\n \"location\": {\n \"name\": \"Train station container hub\",\n \"address\": \"Resedastraat 20\",\n \"postal_code\": \"9000\",\n \"city\": \"Gent\",\n \"state\": \"Oost-Vlaanderen\",\n \"country\": \"BE\",\n \"description\": \"This is the dropoff location of the loaded container\"\n },\n \"note\": \"1000 boxes of shoes\",\n \"date\": \"2024-08-21\",\n \"reference_number\": \"CONT0003\",\n \"planning_instructions\": \"Use mobile number if gate is closed\",\n \"email\": \"info@qargo.com\",\n \"phone_number\": \"02123456\",\n \"mobile_number\": \"+329998888\"\n }\n }\n ],\n \"container\": {\n \"container_scenario\": \"EXPORT\"\n },\n \"customer_reference_number\": \"QARGO_TEST_0003\",\n \"transport_service\": {\n \"code\": \"CONTAINERS\"\n }\n}\n```\n\n### Create a loaded container import transport order\n\nThe following order picks up a filled container, delivers it to our office, and returns the empty container.\nThis examples also demonstrates how to model ADR information.\n\n```json\n{\n \"operation\": \"CREATE\",\n \"consignments\": [\n {\n \"delivery_stop\": {\n \"location\": {\n \"name\": \"Qargo Ghent office\",\n \"address\": \"Gaston Crommenlaan 4\",\n \"postal_code\": \"9050\",\n \"city\": \"Ghent\",\n \"country\": \"BE\"\n },\n \"note\": \"unloading address comments\",\n \"reference_number\": \"D123956\"\n },\n \"pickup_stop\": {\n \"location\": {\n \"address\": \"Europaweg\",\n \"city\": \"Rotterdam\",\n \"country\": \"NL\",\n \"name\": \"APM terminals Maasvlakte II\"\n },\n \"reference_number\": \"P123956\"\n },\n \"goods\": [\n {\n \"good_items\": {\n \"adr\": {\n \"name\": \"DISINFECTANT, LIQUID, CORROSIVE, N.O.S.\",\n \"un_number\": \"1903\"\n }\n },\n \"ordered_quantity\": 100,\n \"ordered_total_volume_value\": 43000,\n \"packaging_type\": {\n \"code\": \"PYZ\"\n }\n }\n ]\n }\n ],\n \"container_number\": \"MSCU5285725\",\n \"container_scenario\": \"IMPORT\",\n \"container_type\": {\n \"code\": \"22G0\"\n },\n \"customer\": {\n \"code\": \"00083\"\n },\n \"customer_reference_number\": \"C2325995\",\n \"order_identifier\": \"ord-12332423\",\n \"teardown_input\": [\n {\n \"location\": {\n \"address\": \"Butaanweg 52-54\",\n \"city\": \"Rotterdam\",\n \"country\": \"NL\",\n \"name\": \"OCC Overbeek Cont. Control.\"\n }\n }\n ],\n \"transport_service\": {\n \"name\": \"Container\"\n }\n}\n```\n\n### Create a loaded container export transport order\n\nThis example shows how to create a transport that exports a loaded container.\nThe setup section specifies the empty container pickup.\n\n```json\n{\n \"operation\": \"CREATE\",\n \"consignments\": [\n {\n \"delivery_stop\": {\n \"location\": {\n \"address\": \"Europaweg\",\n \"city\": \"Rotterdam\",\n \"country\": \"NL\",\n \"name\": \"APM terminals Maasvlakte II\"\n },\n \"reference_number\": \"3432423908987\"\n },\n \"pickup_stop\": {\n \"location\": {\n \"name\": \"Qargo Ghent office\",\n \"address\": \"Gaston Crommenlaan 4\",\n \"postal_code\": \"9050\",\n \"city\": \"Ghent\",\n \"country\": \"BE\"\n },\n \"reference_number\": \"3432441\"\n },\n \"goods\": [\n {\n \"absolute_max_temperature_value\": \"-8.0\",\n \"description\": \"Plastic buckets\",\n \"ordered_quantity\": 1500,\n \"packaging_type\": {\n \"code\": \"PE\"\n }\n }\n ]\n }\n ],\n \"container_number\": \"MSCU5285725\",\n \"container_scenario\": \"EXPORT\",\n \"container_type\": {\n \"code\": \"22RE\"\n },\n \"customer\": {\n \"code\": \"00007\"\n },\n \"customer_reference_number\": \"PUC-888315\",\n \"order_identifier\": \"d18f8309-0f26-4687-b32b-749008a0cb8e\",\n \"setup_input\": [\n {\n \"location\": {\n \"address\": \"Butaanweg 52-54\",\n \"city\": \"Rotterdam\",\n \"country\": \"NL\",\n \"name\": \"OCC Overbeek Cont. Control.\"\n }\n }\n ],\n \"transport_service\": {\n \"name\": \"Container\"\n }\n}\n```\n\n## Adding custom stops\n\nIn Qargo you can define custom stop actions. These stops can be added to configure additional stops related to the order.\n\nThese stops can be defined in the `standalone_stops` property.\n\nUsing `standalone_stops` to configure stops adds the following requirements to the order:\n\n1. Every stop needs to have a unique positive integer assigned to it. This will determine the sequence of the stops in the order.\n2. 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.\n\n**Example custom stops for an order**\n\n```json\n{\n \"import_configuration\": {\n \"code\": \"API\"\n },\n \"transport_service\": {\n \"code\": \"YOUR_TRANSPORT_SERVICE_CODE\"\n },\n \"customer\": {\n \"code\": \"CUSTOMER_CODE\"\n },\n \"operation\": \"CREATE\",\n \"order_identifier\": \"EXT-ORDER-001\",\n \"customer_reference_number\": \"CUST-REF-001\",\n \"consignments\": [\n {\n \"pickup_stop\": {\n \"activity\": \"PICKUP\",\n \"date\": \"2026-04-01\",\n \"location\": {\n \"name\": \"Warehouse Antwerp\",\n \"address\": \"Kaai 100\",\n \"city\": \"Antwerp\",\n \"postal_code\": \"2000\",\n \"country\": \"BE\"\n },\n \"position\": {\n \"optimal\": true,\n \"position\": 1\n }\n },\n \"delivery_stop\": {\n \"activity\": \"DELIVERY\",\n \"date\": \"2026-04-01\",\n \"location\": {\n \"name\": \"Distribution Center Ghent\",\n \"address\": \"Industrieweg 50\",\n \"city\": \"Ghent\",\n \"postal_code\": \"9000\",\n \"country\": \"BE\"\n },\n \"position\": {\n \"optimal\": true,\n \"position\": 3\n }\n },\n \"standalone_stops\": [\n {\n \"activity\": \"CUSTOM\",\n \"custom_activity_label\": \"WEEG\",\n \"date\": \"2026-04-01\",\n \"location\": {\n \"name\": \"Weigh Station Mechelen\",\n \"address\": \"Weegbrug 1\",\n \"city\": \"Mechelen\",\n \"postal_code\": \"2800\",\n \"country\": \"BE\"\n },\n \"position\": {\n \"optimal\": true,\n \"position\": 2\n }\n }\n ],\n \"goods\": [\n {\n \"description\": \"Palletized goods\",\n \"quantity\": 10,\n \"package_type\": \"EURO_PALLET\",\n \"total_weight\": 5000\n }\n ]\n }\n ]\n}\n```\n\n**Example custom stops for an container order**\n\n```json\n{\n \"order_identifier\": \"QARGO_TEST_0005\",\n \"operation\": \"CREATE\",\n \"customer\": {\n \"name\": \"UPS SCS Coventry\"\n },\n \"setup_stops\": [\n {\n \"location\": {\n \"name\": \"Stop 1\",\n \"address\": \"Scheepzatestraat 1\",\n \"postal_code\": \"9000\",\n \"city\": \"Gent\",\n \"state\": \"Oost-Vlaanderen\",\n \"country\": \"BE\"\n },\n \"note\": \"Stop 1 notes\",\n \"date\": \"2024-08-20\",\n \"reference_number\": \"Stop 1 reference number\",\n \"planning_instructions\": \"Stop 1 instructions\",\n \"email\": \"info@qargo.com\",\n \"phone_number\": \"+0912341431\",\n \"mobile_number\": \"+324567890\",\n \"activity\": \"COLLECT_EMPTY_CONTAINER\",\n \"position\": {\n \"position\": 1\n }\n }\n ],\n \"consignments\": [\n {\n \"standalone_stops\": [\n {\n \"location\": {\n \"name\": \"Stop 2\",\n \"address\": \"Vlierstraat 4,\",\n \"postal_code\": \"9000\",\n \"city\": \"Gent\",\n \"state\": \"Oost-Vlaanderen\",\n \"country\": \"BE\",\n \"description\": \"HQ\"\n },\n \"note\": \"Stop 2 notes\",\n \"date\": \"2024-08-20\",\n \"reference_number\": \"Stop 2 number\",\n \"planning_instructions\": \"Stop 2 instructions\",\n \"email\": \"info@qargo.com\",\n \"phone_number\": \"+0912341431\",\n \"mobile_number\": \"+324567890\",\n \"custom_activity\": \"WEGEN\",\n \"position\": {\n \"position\": 2\n }\n },\n {\n \"location\": {\n \"name\": \"Stop 6\",\n \"address\": \"Vlierstraat 4,\",\n \"postal_code\": \"9000\",\n \"city\": \"Gent\",\n \"state\": \"Oost-Vlaanderen\",\n \"country\": \"BE\",\n \"description\": \"HQ\"\n },\n \"note\": \"Stop 6 notes\",\n \"date\": \"2024-08-20\",\n \"reference_number\": \"Stop 6 number\",\n \"planning_instructions\": \"Stop 6 instructions\",\n \"email\": \"info@qargo.com\",\n \"phone_number\": \"+0912341431\",\n \"mobile_number\": \"+324567890\",\n \"custom_activity\": \"WEGEN\",\n \"position\": {\n \"position\": 6\n }\n },\n {\n \"location\": {\n \"name\": \"Stop 3\",\n \"address\": \"Corbiestraat 4,\",\n \"postal_code\": \"9000\",\n \"city\": \"Gent\",\n \"state\": \"Oost-Vlaanderen\",\n \"country\": \"BE\"\n },\n \"note\": \"Stop 3 notes\",\n \"date\": \"2024-08-22\",\n \"reference_number\": \"Stop 3 reference number\",\n \"planning_instructions\": \"Stop 3 instructions\",\n \"email\": \"info@qargo.com\",\n \"phone_number\": \"+0912341431\",\n \"mobile_number\": \"+324567890\",\n \"custom_activity\": \"INKLAREN\",\n \"position\": {\n \"position\": 3\n }\n }\n ],\n \"pickup_stop\": {\n \"location\": {\n \"name\": \"Stop 4\",\n \"address\": \"Gaston Crommenlaan 4,\",\n \"postal_code\": \"9000\",\n \"city\": \"Gent\",\n \"state\": \"Oost-Vlaanderen\",\n \"country\": \"BE\",\n \"description\": \"HQ\"\n },\n \"note\": \"Stop 4 notes\",\n \"date\": \"2024-08-20\",\n \"reference_number\": \"Stop 4 reference number\",\n \"planning_instructions\": \"Stop 4 instructions\",\n \"email\": \"info@qargo.com\",\n \"phone_number\": \"+0912341431\",\n \"mobile_number\": \"+324567890\",\n \"activity\": \"PICKUP_EXPORT\",\n \"position\": {\n \"position\": 4\n }\n },\n \"delivery_stop\": {\n \"location\": {\n \"name\": \"Stop 5\",\n \"address\": \"Resedastraat 20\",\n \"postal_code\": \"9000\",\n \"city\": \"Gent\",\n \"state\": \"Oost-Vlaanderen\",\n \"country\": \"BE\",\n \"description\": \"Delivery\"\n },\n \"note\": \"Stop 5 notes\",\n \"date\": \"2024-08-21\",\n \"reference_number\": \"Stop 5 reference number\",\n \"planning_instructions\": \"Stop 5 instructions\",\n \"email\": \"info@qargo.com\",\n \"phone_number\": \"02123456\",\n \"mobile_number\": \"+329998888\",\n \"activity\": \"DELIVERY_EXPORT\",\n \"position\": {\n \"position\": 5\n }\n }\n }\n ],\n \"container\": {\n \"container_scenario\": \"EXPORT\"\n },\n \"customer_reference_number\": \"QARGO_TEST_0005\",\n \"transport_service\": {\n \"code\": \"CONTAINER_BOOKING\"\n }\n}\n```\n\n## Examples\n\n### Basic order\n\n```json\n{\n \"order_identifier\": \"DEFAULT_ORDER\",\n \"operation\": \"CREATE\",\n \"customer\": { \"name\": \"Qargo\" },\n \"import_configuration\": { \"code\": \"API\" },\n \"consignments\": [\n {\n \"pickup_stop\": {\n \"location\": {\n \"name\": \"Qargo\",\n \"address\": \"Gaston Crommenlaan 4\",\n \"postal_code\": \"9000\",\n \"city\": \"Gent\",\n \"state\": \"Oost-Vlaanderen\",\n \"country\": \"BE\",\n \"description\": \"HQ\"\n },\n \"note\": \"Collection notes\",\n \"date\": \"2024-07-19\",\n \"reference_number\": \"\",\n \"planning_instructions\": \"\",\n \"email\": \"\",\n \"phone_number\": \"\",\n \"mobile_number\": \"\"\n },\n \"delivery_stop\": {\n \"location\": {\n \"name\": \"Qargo London\",\n \"address\": \"71-91 Aldwych\",\n \"postal_code\": \"WC2B 4HN\",\n \"city\": \"London\",\n \"country\": \"GB\",\n \"description\": \"Delivery\"\n },\n \"note\": \"Delivery notes\",\n \"date\": \"2024-07-19\",\n \"reference_number\": \"\",\n \"planning_instructions\": \"\",\n \"email\": \"\",\n \"phone_number\": \"\",\n \"mobile_number\": \"\"\n },\n \"goods\": [{ \"quantity\": 1 }]\n }\n ],\n \"customer_reference_number\": \"QARGO-123\",\n \"transport_service\": { \"code\": \"QARGO\" },\n \"service_level\": { \"code\": \"QARGO_NEXT_DAY\" }\n}\n```\n\n### Container IMPORT scenario\n\n```json\n{\n \"order_identifier\": \"CONTAINER_IMPORT_ORDER\",\n \"operation\": \"CREATE\",\n \"customer\": { \"name\": \"QARGO\" },\n \"import_configuration\": { \"code\": \"API\" },\n \"teardown_stops\": [\n {\n \"location\": {\n \"name\": \"Ghent Container Yard\",\n \"address\": \"Scheepzatestraat 1\",\n \"postal_code\": \"9000\",\n \"city\": \"Gent\",\n \"state\": \"Oost-Vlaanderen\",\n \"country\": \"BE\"\n },\n \"note\": \"Empty container drop-off\",\n \"date\": \"2024-08-24\",\n \"reference_number\": \"\",\n \"planning_instructions\": \"\",\n \"email\": \"\",\n \"phone_number\": \"\",\n \"mobile_number\": \"\"\n }\n ],\n \"consignments\": [\n {\n \"pickup_stop\": {\n \"location\": {\n \"name\": \"Qargo Ghent\",\n \"address\": \"Gaston Crommenlaan 4,\",\n \"postal_code\": \"9000\",\n \"city\": \"Gent\",\n \"state\": \"Oost-Vlaanderen\",\n \"country\": \"BE\",\n \"description\": \"\"\n },\n \"note\": \"\",\n \"date\": \"2024-08-20\",\n \"reference_number\": \"\",\n \"planning_instructions\": \"\",\n \"email\": \"\",\n \"phone_number\": \"\",\n \"mobile_number\": \"\"\n },\n \"delivery_stop\": {\n \"location\": {\n \"name\": \"Qargo London\",\n \"address\": \"71-91 Aldwych\",\n \"postal_code\": \"WC2B 4HN\",\n \"city\": \"London\",\n \"country\": \"GB\",\n \"description\": \"Delivery\"\n },\n \"note\": \"Delivery notes\",\n \"date\": \"2024-08-22\",\n \"reference_number\": \"\",\n \"planning_instructions\": \"\",\n \"email\": \"\",\n \"phone_number\": \"\",\n \"mobile_number\": \"\"\n }\n }\n ],\n \"container\": { \"container_scenario\": \"IMPORT\", \"seal_number\": \"SEAL12345\" },\n \"customer_reference_number\": \"QARGO-01\",\n \"transport_service\": { \"code\": \"CONTAINER_TRANSPORT_SERVICE\" }\n}\n```\n\n### Container EXPORT scenario\n\n```json\n{\n \"order_identifier\": \"CONTAINER_EXPORT_ORDER\",\n \"operation\": \"CREATE\",\n \"customer\": { \"name\": \"QARGO\" },\n \"import_configuration\": { \"code\": \"API\" },\n \"setup_stops\": [\n {\n \"location\": {\n \"name\": \"Ghent Container Yard\",\n \"address\": \"Scheepzatestraat 1\",\n \"postal_code\": \"9000\",\n \"city\": \"Gent\",\n \"state\": \"Oost-Vlaanderen\",\n \"country\": \"BE\"\n },\n \"note\": \"Empty container pickup location\",\n \"date\": \"2024-08-20\",\n \"reference_number\": \"\",\n \"planning_instructions\": \"\",\n \"email\": \"\",\n \"phone_number\": \"\",\n \"mobile_number\": \"\"\n }\n ],\n \"consignments\": [\n {\n \"pickup_stop\": {\n \"location\": {\n \"name\": \"Qargo Ghent\",\n \"address\": \"Gaston Crommenlaan 4,\",\n \"postal_code\": \"9000\",\n \"city\": \"Gent\",\n \"state\": \"Oost-Vlaanderen\",\n \"country\": \"BE\",\n \"description\": \"\"\n },\n \"note\": \"\",\n \"date\": \"2024-08-20\",\n \"reference_number\": \"\",\n \"planning_instructions\": \"\",\n \"email\": \"\",\n \"phone_number\": \"\",\n \"mobile_number\": \"\"\n },\n \"delivery_stop\": {\n \"location\": {\n \"name\": \"Qargo London\",\n \"address\": \"71-91 Aldwych\",\n \"postal_code\": \"WC2B 4HN\",\n \"city\": \"London\",\n \"country\": \"GB\",\n \"description\": \"Delivery\"\n },\n \"note\": \"Delivery notes\",\n \"date\": \"2024-08-22\",\n \"reference_number\": \"\",\n \"planning_instructions\": \"\",\n \"email\": \"\",\n \"phone_number\": \"\",\n \"mobile_number\": \"\"\n }\n }\n ],\n \"container\": { \"container_scenario\": \"EXPORT\", \"seal_number\": \"SEAL12345\" },\n \"customer_reference_number\": \"QARGO-00003\",\n \"transport_service\": { \"code\": \"CONTAINER_TRANSPORT_SERVICE\" }\n}\n```\n\n### Order with multiple stops example\n\n```json\n{\n \"order_identifier\": \"MULTIPLE_STOPS_ORDER\",\n \"operation\": \"CREATE\",\n \"customer\": { \"name\": \"QARGO\" },\n \"consignments\": [\n {\n \"standalone_stops\": [\n {\n \"location\": {\n \"name\": \"Customs Ghent\",\n \"address\": \"Sint-Lievenslaan 27\",\n \"postal_code\": \"9000\",\n \"city\": \"Gent\",\n \"state\": \"Oost-Vlaanderen\",\n \"country\": \"BE\",\n \"description\": \"Customs office location\"\n },\n \"note\": \"\",\n \"date\": \"2024-08-20\",\n \"reference_number\": \"\",\n \"planning_instructions\": \"\",\n \"email\": \"\",\n \"phone_number\": \"\",\n \"mobile_number\": \"\",\n \"custom_activity\": \"CUSTOMS\",\n \"position\": { \"position\": 1 }\n },\n {\n \"location\": {\n \"name\": \"Truck weight station\",\n \"address\": \"Belgicastraat 10\",\n \"postal_code\": \"9000\",\n \"city\": \"Gent\",\n \"state\": \"Oost-Vlaanderen\",\n \"country\": \"BE\",\n \"description\": \"HQ\"\n },\n \"note\": \"\",\n \"date\": \"2024-08-20\",\n \"reference_number\": \"\",\n \"planning_instructions\": \"\",\n \"email\": \"\",\n \"phone_number\": \"\",\n \"mobile_number\": \"\",\n \"custom_activity\": \"WEIGHT_STATION\",\n \"position\": { \"position\": 2 }\n },\n {\n \"location\": {\n \"name\": \"Truckwash Ghent\",\n \"address\": \"Traktaatweg 23\",\n \"postal_code\": \"9000\",\n \"city\": \"Gent\",\n \"state\": \"Oost-Vlaanderen\",\n \"country\": \"BE\"\n },\n \"note\": \"\",\n \"date\": \"2024-08-23\",\n \"reference_number\": \"\",\n \"planning_instructions\": \"\",\n \"email\": \"\",\n \"phone_number\": \"\",\n \"mobile_number\": \"\",\n \"custom_activity\": \"WASHING\",\n \"position\": { \"position\": 5 }\n }\n ],\n \"pickup_stop\": {\n \"location\": {\n \"name\": \"Qargo Ghent\",\n \"address\": \"Gaston Crommenlaan 4,\",\n \"postal_code\": \"9000\",\n \"city\": \"Gent\",\n \"state\": \"Oost-Vlaanderen\",\n \"country\": \"BE\",\n \"description\": \"\"\n },\n \"note\": \"\",\n \"date\": \"2024-08-20\",\n \"reference_number\": \"\",\n \"planning_instructions\": \"\",\n \"email\": \"\",\n \"phone_number\": \"\",\n \"mobile_number\": \"\",\n \"activity\": \"PICKUP\",\n \"position\": { \"position\": 3 }\n },\n \"delivery_stop\": {\n \"location\": {\n \"name\": \"Qargo London\",\n \"address\": \"71-91 Aldwych\",\n \"postal_code\": \"WC2B 4HN\",\n \"city\": \"London\",\n \"country\": \"GB\",\n \"description\": \"Delivery\"\n },\n \"note\": \"Delivery notes\",\n \"date\": \"2024-08-22\",\n \"reference_number\": \"\",\n \"planning_instructions\": \"\",\n \"email\": \"\",\n \"phone_number\": \"\",\n \"mobile_number\": \"\",\n \"activity\": \"DELIVERY\",\n \"position\": { \"position\": 4 }\n }\n }\n ],\n \"customer_reference_number\": \"QARGO_001\",\n \"transport_service\": { \"code\": \"FULL_LOADS\" }\n}\n```\n\n### Order with ADR goods\n\n```json\n{\n \"order_identifier\": \"DANGEROUS_GOODS_ORDER\",\n \"operation\": \"CREATE\",\n \"customer\": { \"name\": \"QARGO\" },\n \"import_configuration\": { \"code\": \"API\" },\n \"consignments\": [\n {\n \"pickup_stop\": {\n \"location\": {\n \"name\": \"Qargo Ghent\",\n \"address\": \"Gaston Crommenlaan 4,\",\n \"postal_code\": \"9000\",\n \"city\": \"Gent\",\n \"state\": \"Oost-Vlaanderen\",\n \"country\": \"BE\",\n \"description\": \"\"\n },\n \"note\": \"\",\n \"date\": \"2024-08-20\",\n \"reference_number\": \"\",\n \"planning_instructions\": \"\",\n \"email\": \"\",\n \"phone_number\": \"\",\n \"mobile_number\": \"\"\n },\n \"delivery_stop\": {\n \"location\": {\n \"name\": \"Qargo London\",\n \"address\": \"71-91 Aldwych\",\n \"postal_code\": \"WC2B 4HN\",\n \"city\": \"London\",\n \"country\": \"GB\",\n \"description\": \"Delivery\"\n },\n \"note\": \"Delivery notes\",\n \"date\": \"2024-08-22\",\n \"reference_number\": \"\",\n \"planning_instructions\": \"\",\n \"email\": \"\",\n \"phone_number\": \"\",\n \"mobile_number\": \"\"\n },\n \"goods\": [\n {\n \"packaged_items\": [\n {\n \"adr\": {\n \"un_number\": \"1956\",\n \"packaging_type\": \"BOX\",\n \"emergency_phone_number\": \"+32456789010\",\n \"technical_name_by_locale\": { \"en\": \"Dangerous goods\" }\n },\n \"quantity\": 5,\n \"total_volume_l\": 100,\n \"total_weight_kg\": 100,\n \"description\": \"Dangerous and flammable goods\"\n }\n ],\n \"description\": \"Fuel\",\n \"quantity\": 1,\n \"product_name\": \"FUEL\"\n }\n ]\n }\n ],\n \"customer_reference_number\": \"QARGO-001\",\n \"transport_service\": { \"code\": \"HAZARDOUS\" },\n \"service_level\": { \"code\": \"NEXT_DAY\" }\n}\n```\n\n### Order with pallets and custom barcodes\n\n```json\n{\n \"order_identifier\": \"PALLETS_WITH_BARCODES_ORDER\",\n \"operation\": \"CREATE\",\n \"customer\": { \"name\": \"QARGO\" },\n \"import_configuration\": { \"code\": \"API\" },\n \"consignments\": [\n {\n \"pickup_stop\": {\n \"location\": {\n \"name\": \"Qargo Ghent\",\n \"address\": \"Gaston Crommenlaan 4,\",\n \"postal_code\": \"9000\",\n \"city\": \"Gent\",\n \"state\": \"Oost-Vlaanderen\",\n \"country\": \"BE\",\n \"description\": \"\"\n },\n \"note\": \"\",\n \"date\": \"2024-08-20\",\n \"reference_number\": \"\",\n \"planning_instructions\": \"\",\n \"email\": \"\",\n \"phone_number\": \"\",\n \"mobile_number\": \"\"\n },\n \"delivery_stop\": {\n \"location\": {\n \"name\": \"Qargo London\",\n \"address\": \"71-91 Aldwych\",\n \"postal_code\": \"WC2B 4HN\",\n \"city\": \"London\",\n \"country\": \"GB\",\n \"description\": \"Delivery\"\n },\n \"note\": \"Delivery notes\",\n \"date\": \"2024-08-22\",\n \"reference_number\": \"\",\n \"planning_instructions\": \"\",\n \"email\": \"\",\n \"phone_number\": \"\",\n \"mobile_number\": \"\"\n },\n \"goods\": [\n {\n \"quantity\": 1,\n \"packaging_type\": {\n \"name\": \"Full Pallet\",\n \"packaging_size\": { \"code\": \"FP\" }\n },\n \"handling_units\": [\n { \"barcode\": { \"value\": \"01J93R8V517R7133FVCM3ZCJNN\" } }\n ]\n },\n {\n \"quantity\": 2,\n \"packaging_type\": {\n \"name\": \"Half Pallet\",\n \"packaging_size\": { \"code\": \"HP\" }\n },\n \"handling_units\": [\n { \"barcode\": { \"value\": \"01J93R9024CNTJJPQG8WDP2PVX\" } },\n { \"barcode\": { \"value\": \"01J93R9PKY3A5C9S6T4VV12C8B\" } }\n ]\n }\n ]\n }\n ],\n \"customer_reference_number\": \"QARGO-0001\",\n \"transport_service\": { \"code\": \"PALLETS\" },\n \"service_level\": { \"code\": \"PREMIUM_NEXT_DAY\" }\n}\n```\n\n\n# Status updates\n\nThe API supports status updates for specific entities. This can either be via an endpoint or webhook.\n\n## Task\n\nThis [endpoint](/docs/api-task/update_task_status_v1_tasks_task__id__update_status_post) allows you to update the status of a task. A task in Qargo is linked to a side effect in an external system.\n\n## Order\n\nYou can change the status of an order via the [webhook](/docs/webhooks-inbound/order-import-webhook) or [endpoint](/docs/api-order/import_order_v1_orders_order_upload_post).\n\n## Stop\n\nThis [webhook](/docs/webhooks-inbound/subcontractor-status-update-webhook) allows you to either update:\n\n1. stops\n2. stop groups\n\nUsing this [webhook](/docs/webhooks-inbound/subcontractor-status-update-webhook) you can provide status updates for stops or stop groups. You can also provide additional information in the payload\nwhich can be mapped to different fields in Qargo.\n\n## Booking\n\nThis [webhook](/docs/webhooks-inbound/intermodal-booking-status-webhook) is not yet available at this time.\n\n# Visibility\n\nWe support visibility (sending messages triggered by Qargo system events) in the api as well.\nThese messages can be send out as a [webhook](/docs/webhooks-outbound/operational_visibility_event_webhook_post), or an EDI connection.\n\nFor most endpoints, visibility only trigger on status changes (for example, from stop `IN_PROGRESS` -> `COMPLETED`).\nThere are a few exceptions, these will be indicated in the overview:\n\n- Order level\n - We send out a visibility event on `ACCEPTED` (order created), `REJECTED` (order skipped) and `COMPLETED` (all stops for order completed).\n- Stop level\n - We send out a visibility event on `AT_STOP` (arrived at stop), `COMPLETED` (all activities completed for stop).\n- Position level (note: for every telematics update)\n- Trip level\n - We send a visibility event when a trip changes to `PLANNED` and when it transitions to `COMPLETED`.\n- Resource level\n - We send an event when a resource is assigned to a certain [trip](/docs/section/concepts/trip).\n# Accounting\n\nThe following section details how to use our api for accounting integrations.\nYou can push/pull accounting information between Qargo and the accounting system.\n\nPlease note that this is not suitable for BI/analytics purposes.\nWe offer a SQL based data warehouse connector to support this use case.\n\n## Synchronize invoices/credit notes\n\nThe flow for sales/purchase invoices and sales credit notes is the same, with a different payload.\nWe will show an example of syncing a sales invoices below\n\nWe use a task oriented approach to indicate which invoice to sync (post in the accounting software).\nThe implementer should take the following steps:\n\n- Fetch a list of available tasks (tasks in a TODO state)\n- For each available task:\n- Fetch the payload in the task details\n- Sync the data to the accounting system.\n- Report the status back, this result can be success or failure.\n\n![Sync invoice/credit note flow](/docs/static/sync_invoice_flow.svg)\n\nIt is allowed to only process a subset of the available tasks and process the remaining invoices later.\n\n### Example\n\nFetch the Invoice/Credit notes to sync using [sync tasks endpoint](/docs/api-accounting/list_invoices_credit_notes_to_sync_v1_accounting_sync_tasks_get)\n\n```\ncurl https://api.qargo.com/v1/accounting/sync-tasks -H 'Content-type: application/json' -H 'Authorization: Bearer *access_token*'\n```\n\nResponse:\n\n```json\n{ \"tasks\": [{ \"id\": \"*id_of_first_task*\" }] }\n```\n\nNote that as long as an endpoint is not marked as completed/failed, it will still show up as an available POST task.\n\nFetch the first payload:\n\n
\ncurl https://api.qargo.com/v1/accounting/sync-tasks/*id_of_first_task* -H 'Content-type: application/json' -H 'Authorization: Bearer *access_token*'\n
\n\nResponse:\n\n
\n{\"id\": \"\", \"status\": \"TODO\", \"task_type\": \"POST_INVOICE\", \"payload\": {....}}\n
\n\n\n\n## Fetch updated customer information\n\n### Example\n\n```\ncurl https://api.qargo.com/v1/company/*id_of_customer* -H 'Content-type: application/json' -H 'Authorization: Bearer *access_token*'\n```\n\nResponse:\n\n```\n{\"id\": \"\", ...}\n```\n\nNote: since we embed the customer/supplier company in the invoice payload, it is possible to synchronise these companies as part of the invoice posting flow.\n\n## Synchronize blocked status of customer\n\n### Example\n\nUpdate the customer blocked status:\n\n```\ncurl -X POST https://api.qargo.com/v1/company/*id_of_customer* -H 'Content-type: application/json' -H 'Authorization: Bearer *access_token*' -d '{\"is_blocked\": true}'\n```\n\nResponse:\n\n```\n{\"id\": \"\", \"is_blocked\": true, ....}\n```\n\n## Creating contacts for a customer or subcontractor\n\nYou can create a contact for a customer or subcontractor by providing a `contacts` list in the payload.\n\n### Example\n\n```\ncurl -X PATCH https://api.qargo.com/v1/company/*id_of_customer* -H 'Content-type: application/json' -H 'Authorization: Bearer *access_token*' -d '{\"contacts\":[{\"name\":\"Contact name\",\"note\":\"Notes on the contact\",\"phone_number\":\"+32456789016\",\"email\":\"hello@qargo.com\",\"roles\":[\"BILLING\",\"OPERATIONS\"]}]}'\n```\n\n## Updating contacts for a customer or subcontractor\n\nTo update a contact, you need to provide the `id` of the contact you want to update in the payload.\n\n### Example\n\n```\ncurl -X PATCH https://api.qargo.com/v1/company/*id_of_customer* -H 'Content-type: application/json' -H 'Authorization: Bearer *access_token*' -d '{\"id\": \"3ba86d22-0183-4575-804d-60e0a6fa2f74\", \"contacts\":[{\"name\":\"Contact name\",\"note\":\"Notes on the contact\",\"phone_number\":\"+32456789016\",\"email\":\"hello@qargo.com\",\"roles\":[\"BILLING\",\"OPERATIONS\"]}]}'\n```\n\n## Archiving a contact for a customer or subcontractor\n\nTo archive a contact, you need to provide the `is_archived` field in the payload along with the `id` of the contact you want to archive.\n\n### Example\n\n```\ncurl -X PATCH https://api.qargo.com/v1/company/*id_of_customer* -H 'Content-type: application/json' -H 'Authorization: Bearer *access_token*' -d '{\"is_archived\": true, \"id\": \"3ba86d22-0183-4575-804d-60e0a6fa2f74\", \"contacts\":[{\"name\":\"Contact name\",\"note\":\"Notes on the contact\",\"phone_number\":\"+32456789016\",\"email\":\"hello@qargo.com\",\"roles\":[\"BILLING\",\"OPERATIONS\"]}]}'\n```\n\n# Resources\n\n## Extras\n\nResources can be associated with stop extras (e.g. ADR, taillift, temperature control) to indicate which extras the resource is compatible with. Extras are specific to your environment — use the TMS UI or ask your Qargo contact to find the codes available.\n\n### Setting extras on create\n\nInclude `extras` in the POST body to set extras when creating a resource.\n\n```json\nPOST /resource\n{\n \"resource_type\": \"TRACTOR\",\n \"name\": \"Truck 01\",\n \"extras\": [\n { \"code\": \"ADR\" },\n { \"code\": \"TAIL\" }\n ]\n}\n```\n\n### Response (all read endpoints)\n\n```json\n{\n \"extras\": [\n { \"id\": \"uuid-1\", \"code\": \"ADR\", \"name\": \"ADR Transport\" },\n { \"id\": \"uuid-2\", \"code\": \"TAIL\", \"name\": \"Taillift\" }\n ]\n}\n```\n\n### Updating extras\n\nProviding `extras` replaces the entire list. Omitting the field leaves existing extras untouched. Send an empty list to clear all extras.\n\n```json\nPATCH /resource/{resource_id}\n{ \"extras\": [{ \"code\": \"TAIL\" }] }\n```\n\n### Error — duplicate code\n\nIf a code matches more than one extra in the tenant, the API returns an error.\n\n```json\nHTTP 400\n{ \"detail\": \"Multiple extras found with code 'TAIL'. Please ensure extra codes are unique, or contact support.\" }\n```\n\n## Unavailabilities\n\n### Creating a unavailability\n\nCreating an unavailability is always for a single resource. Currently no bulk unavailability creation is supported.\n\n```json\n{\n \"reason\": \"DRIVER_HOLIDAY\",\n \"start_time\": \"2025-01-08T00:00:00+00:00\",\n \"end_time\": \"2025-01-12T00:00:00+00:00\",\n \"description\": \"HR reference HR00001\",\n \"external_id\": \"YOUR_REFERENCE_00001\"\n}\n```\n\n### Updating an unavailability\n\nUpdating an unavailability is always for a single resource. Currently no bulk unavailability updates are supported.\n\n```json\n{\n \"reason\": \"DRIVER_HOLIDAY\",\n \"start_time\": \"2025-01-09T00:00:00+00:00\",\n \"end_time\": \"2025-01-12T00:00:00+00:00\",\n \"description\": \"HR reference HR00002, correction 1 day\",\n \"external_id\": \"YOUR_REFERENCE_00001\"\n}\n```\n\n### Deleting an unavailability\n\nDeleting a unavailability will remove the unavailability from the system. This is not reversable.\n# E-invoicing\n\n> E-invoicing refers to the automated, digital exchange of structured invoice data between businesses (e.g., suppliers and buyers) in a standardized format.\n\nWe support receiving purchase invoices and credit notes in multiple formats:\n\n- **JSON** — Qargo's own structured purchase invoice/credit note schema\n- **XML (UBL)** — Peppol-compliant UBL documents\n- **Multipart** — JSON data combined with file attachments (PDF, XML, etc.)\n- **Custom formats** — CSV, EDIFACT, fixed-width, or other proprietary formats via the Qargo integration framework\n\nAttachments (e.g. the invoice PDF, CMR documents) can be included either via the `attachments[].document` object in JSON (with base64-encoded content), or as additional parts in a multipart upload.\n\n## Peppol\n\nFor more information on Peppol E-invoicing, see https://help.qargo.com/en/articles/304774-invoices-peppol-in-qargo.\n\n## Workflows\n\n### Importing E-invoices into Qargo via webhook\n\nThis [endpoint](/docs/use-case-e-invoicing/e-invoicing-webhook) allows importing e-invoices into Qargo. The e-invoice can either be a purchase invoice or a purchase credit note. See the endpoint documentation for detailed format examples and attachment handling.\n\n# Question paths and answers\n\nQuestion paths are a configuration mechanism that maps fields in incoming data to specific fields, documents or actions in Qargo. A `question_answers` dict can be included on updates in two webhooks:\n\n* [Status update](/docs/webhooks-inbound/subcontractor-status-update-webhook) — on stop or stop group updates\n* [Partial order update](/docs/webhooks-inbound/partial-order-update) — on order, consignment, stop, good, or handling unit updates\n\nThe keys of this dict correspond to question paths configured on an integration; the values are the answers.\n\n**Status update example**\n\n```json\n{\n \"updates\": [\n {\n \"event_time\": \"2024-08-20T10:00:00Z\",\n \"stop\": {\n \"id\": \"a2a84715-0027-49af-ad30-494c0ccf75cc\",\n \"status\": \"COMPLETED\",\n \"question_answers\": {\n \"trailer_number\": \"VB-123-AB\"\n }\n }\n }\n ]\n}\n```\n\n**Partial order update example**\n\n```json\n{\n \"updates\": [\n {\n \"match\": {\n \"matches_all\": [\n { \"order\": { \"customer_reference_number\": { \"matches_any\": [\"T1234393\"] } } }\n ]\n },\n \"consignment\": {\n \"updates\": [\n {\n \"good\": {\n \"updates\": [\n {\n \"handling_unit\": {\n \"updates\": [\n {\n \"match\": {\n \"matches_all\": [\n { \"handling_unit\": { \"barcode\": { \"matches_any\": [\"ABC123\"] } } }\n ]\n },\n \"question_answers\": {\n \"scan_barcode\": [\n {\n \"timestamp\": \"2024-08-20T10:00:00Z\",\n \"status\": \"SCANNED_IN\",\n \"stop_location_code\": \"DEPOT-001\",\n \"stop_match\": {\n \"location\": {\n \"postal_code\": { \"matches_any\": [\"NW1 2AB\"] }\n }\n }\n }\n ]\n }\n }\n ]\n }\n }\n ]\n }\n }\n ]\n }\n }\n ]\n}\n```\n\n## Actions\n\nApart from updating fields and documents, question paths can be configured to trigger one of the following actions.\n\n### `assign_resource`\n\nAssigns a resource (trailer, container, or full trailer) to an order or trip based on a plain-text identifier.\nIf no matching resource is found the answer is silently ignored.\n\n**Answer format**: plain string — the resource's name, code, licence plate, or container number.\n\n```\nVB-123-AB\n```\n\nMatching strips all non-alphanumeric characters and is case-insensitive, so `VB-123-AB`, `VB 123 AB`, and `VB123AB` all resolve to the same resource. \n\n### `scan_barcode`\n\nRecords a barcode scan event on a handling unit. An optional stop match is provided, which if matched will record which stop the scan is related to alongside the scan. If the stop is not matched the scan will still succeed, but the stop will not be recorded.\n\n**Answer format**: JSON array of scan objects.\n\n```json\n[\n {\n \"timestamp\": \"2024-08-20T10:00:00Z\",\n \"status\": \"SCANNED_IN\",\n \"stop_location_code\": \"DEPOT-001\",\n \"stop_match\": {\n \"location\": {\n \"postal_code\": { \"matches_any\": [\"NW1 2AB\"] }\n }\n }\n }\n]\n```\n\n| Field | Type | Required | Description |\n| -------------------- | ----------------- | -------- | --------------------------------------------------------------------------------------------------------------------------- |\n| `timestamp` | ISO 8601 datetime | Yes | Time of the scan event |\n| `status` | string | No | Scan status (see below) |\n| `barcode` | string | No | Barcode value; used to identify the handling unit. Optional as the unit will have been matched in the partial order update. |\n| `stop_match` | object | No | Criteria for matching the scan to a specific stop on the trip (see below) |\n| `stop_location_code` | string | No | Location identifier code |\n| `description` | string | No | Free-text description |\n\n#### `stop_match` fields\n\n| Field | Type | Description |\n| ------------------ | ------ | -------------------------------------------------------------------- |\n| `stop_type` | string | Type of stop to match: `PICKUP` or `DELIVERY` |\n| `id` | object | Match by stop ID: `{ \"matches_any\": [\"\"] }` |\n| `reference_number` | object | Match by stop reference number: `{ \"matches_any\": [\"\"] }` |\n| `location` | object | Match by the stop's location (see below) |\n\n#### `stop_match.location` fields\n\n| Field | Type | Description |\n| -------------- | ------ | -------------------------------------------------------------- |\n| `id` | object | Match by location ID: `{ \"matches_any\": [\"\"] }` |\n| `name` | object | Match by location name: `{ \"matches_any\": [\"\"] }` |\n| `postal_code` | object | Match by postal code: `{ \"matches_any\": [\"\"] }` |\n| `country_code` | object | Match by country code: `{ \"matches_any\": [\"\"] }` |\n\nAvailable status values:\n\n| Value | Description |\n|---------------|---------------------------------------------------------------------|\n| `SCANNED_IN` | Handling unit has been scanned in at a pickup stop or at a depot |\n| `STORED` | Handling unit is in storage at a depot |\n| `SCANNED_OUT` | Handling unit has been scanned out of a depot or at a delivery stop |\n"},"compilationErrors":[],"markdown":{"partials":{},"variables":{"rbac":{"teams":["anonymous"]},"user":{},"remoteAddr":{"hostname":"api-docs.qargo.com","port":4000,"ipAddress":"216.73.217.151"},"lang":"default_locale","env":{"PUBLIC_REDOCLY_BRANCH_NAME":"main"}}},"pagePropGetterError":{"message":"","name":""}},"slug":"/docs","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}