Qargo TMS Subcontractor/fleet API (1.2.0)

Subcontractor/fleet dispatch 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).

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

Webhooks

Added: Stop matching now reaches depot stops. StopMatch.stop_type accepts DEPOT_UNLOAD and DEPOT_LOAD, and the new StopMatch.leg object narrows a match to the leg a stop bounds via leg_type (PICKUP, TRANSFER, DELIVERY, DIRECT, EMPTY). From three legs onwards each depot stop type occurs more than once per consignment, so leg must be supplied alongside stop_type; ambiguous matches are left unresolved rather than guessed.
- Affects: Fleet dispatch, Order, Subcontractor dispatch
- Endpoints: POST /v1/webhook/fleet-status-update, POST /v1/webhook/partial-order-update, POST /v1/webhook/subco-status-update

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}

Outgoing data

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

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-15

Outgoing data

Added: The location dispatch webhook now includes a per-consignment tracking_link.
- Affects: Location booking

2026-06-03

Outgoing data

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

2026-05-18

API

Added: The TaskType enum gains DISPATCH, returned by the available-tasks and task endpoints.
- Affects: Accounting, Task

2026-03-23

Outgoing data

Added: Fleet and subcontractor dispatch payloads now include custom_fields.
- Affects: Fleet dispatch, Subcontractor dispatch

2026-03-11

Webhooks

Added: Fleet status-update webhooks accept stop-group ETA windows via eta_start and eta_end.
- Affects: Fleet dispatch
- Endpoints: POST /v1/webhook/fleet-status-update

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-02-24

Webhooks

Added: Fleet status-update webhooks accept stop ETA windows via eta_start and eta_end.
- Affects: Fleet dispatch, Subcontractor dispatch
- Endpoints: POST /v1/webhook/fleet-status-update, POST /v1/webhook/subco-status-update

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