---
title: "Integrations – Qargo API – What, why & how"
description: "Learn how to connect Qargo to external systems for orders, load updates, master data, and accounting, including API setup, credentials, testing, and troubleshooting."
url: https://help.qargo.com/us/articles/865547-integrations-qargo-api-what-why-how
locale: us
updated: 2026-11-03
---

# Integrations – Qargo API – What, why & how

:::callout{tone="info"}
💬 Email [success@qargo.com](mailto:success@qargo.com) to start an integration request or to enable any prerequisite configuration.
:::

## Introduction {#h_ac41125bec}

**What is the Qargo API?**

-   A set of connections that let other systems send data to Qargo and receive data from it.
-   It covers order capture and statuses, load operations with contract carriers, master data sync, and accounting.

**Why use it?**

-   It removes double entry between Qargo and the other systems a transportation company works with, such as customer systems, contract carrier systems, accounting packages, and fleet or HR tools.
-   Data stays up to date in both systems without manual imports.

**How does it work?**

-   Qargo assigns an _integrator ID_ to the party building the connection.
-   A _Super Admin_ creates an _API client_ for the right _role_ and shares the credentials securely.
-   Qargo completes any setup needed on the account. The integration is then tested and goes live.

## Prerequisites {#h_dbbc5364d0}

-   **Super Admin** rights in Qargo.
-   An _integrator ID_ issued by Qargo (see _Step 1_ below).
-   For the _Customer_ role: **Customer portal access** turned on for the relevant customer.
-   For Accounting clients that post invoices: an Accounting API integration set up and linked to the correct _billing entity_.

## Integration types {#h_5966c3f172}

There are three integration types. The type determines how the integration is set up.

-   **Tenant**: a direct connection between Qargo and a third-party system used by the transportation company, for example an accounting package.
-   **Customer**: a connection from a customer's own system into Qargo, for example to submit orders through the customer portal.
-   **Contract carrier**: a connection from a contract carrier's own system into Qargo, for example to send load updates from its own TMS back to Qargo.

## Use cases {#h_664a4407e6}

-   A customer wants to send orders straight from its own system into Qargo instead of typing them into the customer portal.
-   A contract carrier wants to receive load assignments and send stop updates and PODs back from its own TMS.
-   A new driver or vehicle added in an external fleet or HR system should appear automatically in Qargo resources.
-   Finance wants invoices and credit memos to flow into the accounting package, with payment statuses sent back to Qargo.
-   A group with several legal entities wants each entity's accounting system to post only its own invoices.

## Terminology {#h_ef2b99bccb}

| **Term** | **Definition** |
| --- | --- |
| _API_ | A way for two systems to exchange data automatically. |
| _Tenant_ | The Qargo account itself, meaning the transportation company using Qargo. |
| _Integration type_ | Who the connection is set up for: the tenant, one of its customers, or one of its contract carriers. |
| _API client_ | A set of login details (a client ID and a _secret_) that lets an external system connect to Qargo for one _role_. |
| _Role_ | The type of access an API client has: Order management, Customer, Master data management, or Accounting. |
| _Integrator ID_ | A unique ID from Qargo that identifies who is building the integration, so the right person can be contacted if an issue arises. |
| _Secret_ | The private key shown once when an API client is created. It cannot be viewed again. |
| _Master data_ | Core records such as customers, contract carriers, drivers, and vehicles. |
| _Billing entity_ | The legal or internal company in the group that issues an invoice. |
| _POD_ | Proof of delivery: the signed document or photo confirming a delivery. |
| _Order Export_ | An endpoint that returns the full data of an existing order, used as a template for building new order requests. |
| _Order import configuration_ | Account-level settings, managed by Qargo, that control how orders received over the API enter Qargo. |
| _API check_ | The first step of an order import. Qargo checks that the message is built correctly (payload validation). |
| _Qargo import_ | The second step of an order import. Qargo applies the data to the account (tenant validation). |

* * *

## Setting up an API connection {#h_dacd260685}

### Step 1: Request the integration and an integrator ID {#h_7a4480cad0}

1.  **Email** [success@qargo.com](mailto:success@qargo.com) to start the integration request.
2.  **Provide** the following details:

    -   **Integration partner**: company details, plus the name and email of the main contact Qargo will work with. If a third party or external integrator is building the connection, give their details rather than the Qargo account holder's.
    -   **Type and scope**: the type of integration needed (for example order capture) and the expected functionality. See _Related documentation_ at the end of this article.
    -   **Specific requirements**: any specific functional requirements.
3.  **Wait** for an Integrations Delivery Manager (IDM) to get in touch. Qargo then issues the _integrator ID_.

### Step 2: Add an API client for the required role {#h_e9b1ab14b3}

1.  **Navigate** to **Configuration > Organization settings > Users** and scroll to the bottom of the page.
2.  **Click** **Add API client**.

![](https://help.qargo.com/media/de2dd24867ac-image.png)

1.  **Select** the role needed:

    -   [Accounting](https://api.qargo.com/ca849acf3cb543a1975722a2882b7712/docs#tag/Use-case-Accounting): for posting invoices, see _[Accounting API and billing entities](#h_8268f9d1d9)_ below
    -   [Customer](https://api.qargo.com/customer21704fc3a2dc66a58d59414b/docs): used when a customer of the account wants to connect over the API
    -   [Master data management](https://api.qargo.com/ca849acf3cb543a1975722a2882b7712/docs#tag/Use-case-Master-data-sync)
    -   [Order management](https://api.qargo.com/ca849acf3cb543a1975722a2882b7712/docs#tag/Use-case-Order)

### Step 3: Fill in the client details {#h_0d48e98b07}

![](https://help.qargo.com/media/a4e7de110537-image.png)

-   **Integrator ID**: always required. Enter the ID received from Qargo.
-   **Company**: required only for the _Customer_ role.

    ![](https://help.qargo.com/media/7d9d7e88bb30-image.png)


:::callout{tone="info"}
🧰 For the _Customer_ role, **Customer portal access** must be turned on for the relevant customer before an API client can be created.
:::

### ‼️ Step 4: Copy the secret before saving‼️ {#h_5d8948d080}

![](https://help.qargo.com/media/32a5e44416c6-image.png)

:::callout{tone="warning"}
‼️ **The _secret_ is shown only once.** Copy it to a safe place before clicking **Save** and closing the **Add API client** screen. It cannot be viewed again afterward, and a new client would need to be created.
:::

### Step 5: Share the credentials securely {#h_f2132d724b}

**Share** the client ID and secret securely with the party building the integration.

### Step 6: Let Qargo know {#h_293f38389d}

**Notify** Qargo once the clients are set up. Some extra account-level setup may be needed before testing starts, for example order import mapping for the order API, or Accounting API setup.

* * *

## Testing the order API {#h_b17ab36a5e}

The easiest way to start is to create a few typical test orders manually in Qargo, then use them as a template for building API requests.

### Get a template with Order Export {#h_668cb7e95e}

1.  **Open** a test order in Qargo and copy the _order\_id_ from the URL (the part after _orders/_).
2.  **Call** the _Order Export_ endpoint:\
    _GET\<[https://api.qargo.com/v1/orders/order/{order\_id}/export](https://api.qargo.com/v1/orders/order/%7Border_id%7D/export)\>_

3.  **Review** the returned data. Comparing a real Qargo order with its data structure shows how each field needs to be filled in.

![](https://help.qargo.com/media/efbd7ced6dec-image.png)

### Create a new order {#h_50d96770f0}

1.  **Remove** auto-generated fields such as barcodes.
2.  **Include** the import configuration code (by default this is _API_).
3.  **Change** unique identifiers, such as the customer reference number and _order\_identifier_.
4.  **Upload** the order **POST \<[https://api.qargo.com/v1/orders/order/upload](https://api.qargo.com/v1/orders/order/upload)\>**

The order then appears in either the **Orders** tab or the **Order imports** tab, depending on the order import configuration.

![](https://help.qargo.com/media/84ea7382b342-image.png)

* * *

## Order import configuration {#h_8f2bedce55}

Order import configuration is set at the account level and can only be changed by Qargo. These settings control how orders received over the API behave.

:::callout{tone="info"}
📚 For more detail on mapping and errors, see [Integrations – Importing orders into Qargo](https://help.qargo.com/us/articles/450378-integrations-importing-orders-into-qargo).
:::

| **Setting** | **What it does** |
| --- | --- |
| _Automatically create orders_ | Sends imported orders straight to the **Orders** tab, or to the **Order imports** tab, where they must be confirmed first. |
| _Enable updates_ | Controls whether updates are accepted over the API. |
| _Enable detection of duplicates_ | Flags duplicate imports automatically so they are not imported twice. |
| _Apply changes automatically_ | Applies changes without manual checks. Can be limited to a chosen order status, after which updates need manual approval again. |
| _Apply cancellations automatically_ | Works the same way as _Apply changes automatically_, but for cancellations. |

:::callout{tone="info"}
📚 During testing, _Automatically create orders_ is often turned off. This keeps API test orders separate from the orders other teams create manually.

📚 Orders that pass the API check but fail in Qargo always land in the **Order imports** tab, where a key user or admin can review and fix the error.

📚 **Example:** many companies accept updates automatically until an order is planned. To set this up, turn on _Apply changes automatically_ and turn it off from status _Planned_ onward.

![](https://help.qargo.com/media/937c3caabb24-image.png)
:::

:::callout{tone="note"}
‼️ **Different rules for the Customer API.** For the _Customer_ role, updates and cancellations follow the customer portal rules, not the order import configuration. If customers cannot edit orders in the customer portal, they cannot edit them automatically over the API either. Updates can still be sent, but each one must be approved in the order import screen.
:::

* * *

## Checking that an order import worked {#h_0cf7fd7820}

Qargo checks an order sent over the API in two steps. A pass in step 1 does not mean the order exists in Qargo.

| **Step** | **What happens** | **Where the result shows** |
| --- | --- | --- |
| 1\. _API check_ | Qargo checks that the message is built correctly. | In the validation response sent back to the external system. |
| 2\. _Qargo import_ | Qargo applies the data to the account. The order is created or updated. This runs after step 1, in the background. | In the import status, and on the order in Qargo. |

### What the API check confirms {#h_0fb2e846b9}

-   The message follows the expected structure (JSON or XML).
-   Required fields are present, with the right data types and formats.
-   Values such as units and order types are allowed.

### What the API check does not confirm {#h_a8ead373e6}

-   The customers, locations, products, and resources in the order exist in the Qargo account.
-   Business rules and account configuration allow the order to be created or changed.
-   The order reference matches correctly, so Qargo creates a new order or updates the right existing one.
-   An existing order is still in a status that allows changes.

A Qargo import can fail or be rejected even when the API check passed.

### Confirm that an import succeeded {#h_754ec40674}

1.  **Do not** treat a positive API check as confirmation that the order exists.
2.  **Check** the import status of the order. A status of _error_ means the Qargo import failed. A manual correction in Qargo is needed.
3.  **Open** the **Order imports** tab, or the order in Qargo, to review the result.
4.  **Send** Qargo Support the order reference, the timestamp, and the error message if the import still fails.

:::callout{tone="note"}
📚 The _API check_ and the _Qargo import_ are separate steps. The same order can pass the first and fail the second.
:::

#### Examples: API check and Qargo import results {#h_c4e435ac7f}

##### API fail (= API validation fail) {#h_c093b0fa78}

![](https://help.qargo.com/media/d9450d5977b3-image.png)

##### API success {#h_7c0daf9eb8}

![](https://help.qargo.com/media/081d0524a663-image.png)

##### API status upsert error (= UI import fail) {#h_eb776ba8b1}

![](https://help.qargo.com/media/16f5cd91fc4a-image.png)

##### Order import error screen (= UI import fail) {#h_29828d88b6}

![](https://help.qargo.com/media/970394050278-order-imports-list-green.png)

##### Order import fix (UI) {#h_47c23c97a3}

![](https://help.qargo.com/media/f547d77c2c75-fix-order-data-form-green.png)

##### Order import fix (API) {#h_9219b01e67}

![](https://help.qargo.com/media/8d93863219cb-image.png)

* * *

## Accounting API and billing entities {#h_8268f9d1d9}

The Accounting API supports **multiple billing entities**. This gives tighter security and access control for groups that invoice from more than one company.

### What is included {#h_eb25d542bf}

-   **Billing entity on invoices**: the invoice endpoints include a _billing\_entity_ section showing which entity an invoice belongs to.
-   **Multiple integrations**: several Accounting API integrations can be created, each linked to one billing entity.
-   **Filtering**: invoices and tasks can be filtered by their billing entity.
-   **Dedicated API clients**: Accounting API clients are created in the _Accounting API Integration_ settings page. These clients are needed for full functionality.

![](https://help.qargo.com/media/49d0bede7085-image.png)

### How it affects external integrations {#h_666d05b4a7}

-   **Restricted posting**: an integrator can only complete (post) invoices for the billing entity linked to its credentials.
-   **Viewing**: invoices for other billing entities stay visible, subject to normal viewing permissions, but cannot be posted.
-   **Where credentials are created matters:**

    -   To post invoices (set the status to _completed_), credentials must be created in the _Accounting API Integration_ settings page and linked to the correct billing entity.
    -   Credentials created in _Organization settings_ **cannot** set an invoice to _completed_ or list invoices still waiting to be synchronized.

:::callout{tone="note"}
‼️ Accounting clients created in _Organization settings_ cannot post invoices. Always create clients that post invoices in the _Accounting API Integration_ settings page.

![](https://help.qargo.com/media/2ccec67f2cc8-image.png)
:::

* * *

## Troubleshooting {#h_e26ff07754}

| **Issue** | **Resolution** |
| --- | --- |
| Test orders do not appear in the **Orders** tab | With _Automatically create orders_ turned off, imports go to the **Order imports** tab and must be confirmed there. |
| The API check passed, but the order is not in Qargo | The Qargo import may have failed. Check the import status and the Order imports tab. See Checking that an order import worked. |
| The API check passed, but the order is not in Qargo | The Qargo import may have failed. Check the import status and the **Order imports** tab. See _Checking that an order import worked_. |
| An order imported over the API shows an error in Qargo | Errors that do not block the API land in the **Order imports** tab. A key user or admin can review and fix them there. An import status of error means the Qargo import failed and a manual correction is needed. |
| The secret was lost after closing the screen | The secret cannot be recovered. Create a new API client and copy the secret before saving. |
| An API client cannot be created for the _Customer_ role | Turn on **Customer portal access** for that customer first. |
| An Accounting client cannot post invoices | Create the client in `Accounting API Integration settings` and link it to the correct billing entity. Clients from `Organisation settings` cannot post. |
| An integrator cannot post some invoices | Those invoices belong to a different billing entity. Use credentials linked to that billing entity. |
| Duplicate orders keep being imported | Ask Qargo to turn on _Enable detection of duplicates_. |
| Customer API updates are not applied automatically | This is expected. Customer updates follow the customer portal rules and must be approved in the order import screen. |

* * *

## FAQs {#h_07de834c15}

**Q. Does Qargo offer an API?**\
**_A. Yes!_** Qargo offers APIs for order capture and statuses, load operations, master data sync, and accounting, across the Tenant, Customer, and Contract carrier integration types.

* * *

**Q. Can an API connection be set up without Qargo?**\
**_A. No._** Setting up an integration requires **Super Admin** rights and support from the Qargo team. Start by emailing [success@qargo.com](mailto:success@qargo.com).

* * *

**Q. Can one Accounting integration post invoices for every billing entity?**\
**_A. No._** Each Accounting API client can only post invoices for the billing entity it is linked to. Invoices for other entities stay visible but cannot be posted.

* * *

## Related documentation {#h_cc6c5591eb}

**API reference documentation ([api.qargo.com](http://api.qargo.com))**

-   [Qargo TMS API – Tenant: Order](https://api.qargo.com/ca849acf3cb543a1975722a2882b7712/docs#tag/Use-case-Order)
-   [Qargo TMS API – Customer specification](https://api.qargo.com/customer21704fc3a2dc66a58d59414b/docs)
-   [Qargo TMS API – Contract carrier specification](https://api.qargo.com/dispatch164648e0838e990ed2d2b195/docs)
-   [Qargo TMS API – Master data sync](https://api.qargo.com/ca849acf3cb543a1975722a2882b7712/docs#tag/Use-case-Master-data-sync)
-   [Qargo TMS API – Accounting](https://api.qargo.com/ca849acf3cb543a1975722a2882b7712/docs#tag/Use-case-Accounting)


## Related articles

- [FAQ: What is billing entity support in the Accounting API, and how does it affect external integrations?](https://help.qargo.com/us/articles/482772-faq-what-is-billing-entity-support-in-the-accounting-api-and-how-does-it-affect.md)
- [INTEGRATIONS - Connect an AI assistant to Qargo over MCP - Walkthrough](https://help.qargo.com/us/articles/799560-integrations-connect-an-ai-assistant-to-qargo-over-mcp-walkthrough.md)
- [INTEGRATIONS - Claude: connect to Qargo over MCP - Walkthrough](https://help.qargo.com/us/articles/799799-integrations-claude-connect-to-qargo-over-mcp-walkthrough.md)
- [FAQ – Qargo API: available options](https://help.qargo.com/us/articles/320484-faq-qargo-api-available-options.md)
- [Integrations: what, why and how](https://help.qargo.com/us/articles/348704-integrations-what-why-and-how.md)
