# Authentication Sign in with your login's email and password to get a token, then send the token as a bearer token on every other call. A few calls need no token: [Sign in](/reference/sign-in), [List countries](/reference/list-countries) and [List currencies](/reference/list-currencies). ## Sign in `POST /client_api/v2/auth/sign_in` ```bash curl -X POST "https://sandbox-api.vatit-stream.com/client_api/v2/auth/sign_in" \ -H "Content-Type: application/json" \ -d '{ "api_user": { "email": "integrations@globaltradecorp.example", "password": "your-password" } }' ``` The answer holds the token: ```json { "token": "eyJhbGciOiJIUzI1NiJ9.eyJlbWFpbCI6ImludGVncmF0aW9ucy4uLiJ9.tQ3m0Yk9v1S7bT2n5Zq8Lw4HcXr6JdPaUeVgNiOfMhA" } ``` A wrong email or password answers `401`: ```json { "success": false, "error": "Invalid email or password", "errors": [] } ``` ## Using the token Send it in the `Authorization` header of every other call: ```bash curl "https://sandbox-api.vatit-stream.com/client_api/v2/orders" \ -H "Authorization: Bearer $API_TOKEN" ``` A token lasts **one week**. Sign in again before then, or when a call answers `401`. ## When a call answers 401 A `401` always means: sign in again. Its `error` says why: | `error` | Why | |---|---| | `You need to sign in or sign up before continuing.` | The call sent no token. | | `Signature has expired` | The token is more than a week old. | | `revoked token` | The token was signed out. | | `Signature verification failed` | The token was changed, or comes from the other environment. | | `Invalid base64 encoding` | The header doesn't hold a whole token. | A `403` is different: your token is fine, but your login isn't allowed to do this, for example creating companies without the reseller permission. Signing in again won't help. ## Keeping it safe - Call the API from your server, never from a browser or a mobile app, so the token and your password stay out of your users' hands. - Keep the password and the token out of source control. Read them from your environment or a secrets store. - Sandbox and production have separate logins. A sandbox token doesn't work on production. --- # Errors Every error the API answers has the same shape: ```json { "success": false, "error": "Purpose of shipment can't be blank", "errors": ["Purpose of shipment can't be blank"] } ``` - `error` is one sentence, ready to show a person. - `errors` lists each reason separately, for your code. It is empty when there is a single cause, such as a missing record. The status code says what kind of error it is. | Status | Meaning | Example `error` | |---|---|---| | `400` | The body isn't valid JSON, or something failed on our side. | `Malformed request body` | | `401` | The token is missing, expired or invalid. Sign in again. See [Authentication](/authentication). | `You need to sign in or sign up before continuing.` | | `403` | Your login isn't allowed to do this. | `You are not authorized to perform that action` | | `404` | The record doesn't exist, or belongs to another company. | `Couldn't find Order with 'id'=0` | | `422` | We refused the request, and `errors` lists each reason. | `Purpose of shipment can't be blank` | | `429` | Too many requests. Wait a minute and try again. | `Too many requests, please wait and try again` | A `400` reading `Unexpected error occurred, please check inputs` means the request reached us but failed on our side. We are told about it automatically. If it keeps happening with the same request, tell us, with the time and the call you made. ## A refusal with several reasons When a request breaks more than one rule, `errors` holds one entry per rule and `error` joins them into a sentence: ```json { "success": false, "error": "Target url can't be blank and Target url is invalid", "errors": ["Target url can't be blank", "Target url is invalid"] } ``` ## What to retry - `429`: wait until the minute is up, then send the same request again. - `400` with `Unexpected error occurred`: retrying the same request rarely helps. Check the inputs first. - `401`: sign in again, then retry with the new token. - `403`, `404` and `422`: don't retry unchanged. The answer will be the same until the request changes. - [Create a waybill](/reference/create-a-waybill) after a timeout: don't retry blindly. Read the order first, and call again only if it has no waybill. --- # Hub shipments Route a shipment through one of our consolidation hubs instead of shipping directly from origin to destination. ## What is hub transit? By default a quote ships **directly** from origin to destination. With **hub transit**, we route the shipment through an intermediate **hub** and split it into **two legs**: - **Clearance leg** — the international leg from your origin into the hub region. This is the leg that clears customs. - **Local leg** — the domestic / final-mile leg from the hub on to the destination. You never choose the hub yourself. When you ask for hub transit, we select an eligible hub for your origin → destination lane and build both legs for you. Hub routing can unlock better rates and consolidated handling on lanes where it's supported. ## Requesting a hub quote Set `hub_transit: true` in the [Create a quote](/reference/create-a-quote) request body. Everything else is identical to a direct quote. ```json { "hub_transit": true, "origin_address": { "name": "John Doe", "company": "Tech Corp", "address_1": "123 Tech Street", "city": "Johannesburg", "province": "Gauteng", "postal_code": "2196", "country_id": 226, "email": "john@techcorp.example", "phone": "+27123456789", "classification": "business" }, "destination_address": { "name": "Jane Smith", "company": "UK Business", "address_1": "456 London Road", "city": "London", "province": "London", "postal_code": "SW1A 2AA", "country_id": 70, "email": "jane@ukbusiness.example", "phone": "+442012345678", "classification": "business" }, "purpose_of_shipment_id": 8, "value_of_goods": "600.00", "value_of_goods_currency_id": "ZAR", "mass_unit": "kg", "distance_unit": "cm", "packages": [ { "weight": 5.5, "width": 30.0, "height": 20.0, "length": 40.0 } ] } ``` The `country_id` and `purpose_of_shipment_id` values above are examples. Take the real ids from [List countries](/reference/list-countries) and [List purposes of shipment](/reference/list-purposes-of-shipment). If **no hub serves the route**, the request fails with `422 Unprocessable Content`: ```json { "success": false, "error": "Hub transit No hub is available for this route.", "errors": ["Hub transit No hub is available for this route."] } ``` When that happens, fall back to a direct quote (omit `hub_transit`, or send `false`). ## What a hub quote returns A hub quote **collapses the two legs into a single estimate per service**, so you compare hub options exactly like direct ones — you don't see or pick legs individually. - `hub_transit` on the quote is `true`. - Each entry in `estimates` is **anchored on the clearance leg**: `estimate_id` is the clearance-leg estimate id (this is the id you pass when creating the order). - `line_items` are the **combined costs of both legs**, grouped by description and summed in your account currency — so the price you see is the all-in hub price, not just one leg. ```json { "quote": { "id": 1234, "dirty": false, "hub_transit": true, "errors": [], "estimates": [ { "estimate_id": 55788, "shipping_company": "FedEx", "shipping_service": "Express Priority", "quote_expired": false, "line_items": [ { "description": "Base Rate", "cost": 1450.00, "currency_id": "ZAR" }, { "description": "Fuel Surcharge", "cost": 217.50, "currency_id": "ZAR" } ], "billable_weights": { "...": "same breakdown as a standard estimate" } } ] } } ``` > Each `cost` above is the **sum across both legs** (clearance + local) for that line item — a hub estimate is one combined price, not two. ## Placing a hub order Create the order exactly as you would for a direct quote — pass the hub estimate's `estimate_id` as `quote_estimate_id` to [Create an order](/reference/create-an-order). There is **nothing hub-specific to send**. The resulting order spans both hub legs. ### The hub lane is fixed at quote time The route — **origin → hub → destination** — is locked when the hub quote is created. The `origin_address` and `destination_address` you send when placing the order **do not re-route a hub order**: they are ignored for routing (only `origin_address.export_code` is read, for the export licence). This keeps the order on the exact lane the rate was quoted for. To ship a different origin or destination, request a **new** hub quote (`hub_transit: true`) for that lane and order from it — you can't re-point an existing hub order at order time. ## Waybills & documents for both legs A hub order has two legs, each with its own waybill. Generating waybills ([Create a waybill](/reference/create-a-waybill)) produces one for **both** legs. To retrieve them, read the order's **`shipments`** array, returned by [Create an order](/reference/create-an-order), [Get an order](/reference/get-an-order) and [Create a waybill](/reference/create-a-waybill). The array is **ordered by route**: the first entry is the leg leaving your origin (**origin → hub**), and the last is the onward leg into your destination (**hub → destination**). A shipment carries no leg-role field, so **use this ordering** to tell the legs apart — `shipments[0]` is always the first leg of the journey, `shipments[1]` the next. Each entry carries that leg's own: - `waybill` — the waybill / tracking number - `waybill_document_link` — the waybill PDF for that leg - `tracking_link` and `status` ```json "shipments": [ { "shipping_service": "...", "waybill": "WB-ORIGIN-TO-HUB", "waybill_document_link": "https://.../leg-1-waybill.pdf", "tracking_link": "...", "status": "..." }, { "shipping_service": "...", "waybill": "WB-HUB-TO-DESTINATION", "waybill_document_link": "https://.../leg-2-waybill.pdf", "tracking_link": "...", "status": "..." } ] ``` On a hub order the order's **top-level** `waybill`, `waybill_document_link`, `tracking_link` and `status` describe a **single leg**, so always read those per leg from `shipments[]`, in route order, to get **both** waybills. ### Documents Documents you upload with [Create an order](/reference/create-an-order) attach once, to the leg that clears customs. On EU hub lanes the local leg is domestic or intra-EU and needs no commercial invoice, so one upload covers the order. ### Pickups Both pickup calls ([List pickup slots](/reference/list-pickup-slots) and [Book a pickup](/reference/book-a-pickup)) work on the first leg, the one leaving your origin. There is nothing for you to schedule on the hub → destination leg. ### Cancelling [Cancel an order](/reference/cancel-an-order) cancels both legs together. ## End-to-end flow 1. **Quote** — `POST /quotes` with `hub_transit: true` → a hub quote whose estimates are collapsed and clearance-anchored. 2. **Choose** — pick an estimate and read its `estimate_id`. 3. **Order** — `POST /orders` with that `quote_estimate_id` → a two-leg hub order; both legs' estimates are accepted automatically. 4. **Waybills** — `POST /orders/{id}/waybills` readies both legs; read each leg's waybill from `shipments[]`. 5. **Pickup** — `GET /orders/{id}/pickup_availabilities` then `POST /orders/{id}/schedule_pickups`, both for the first leg. 6. **Track** — poll `GET /orders/{id}` and read `shipments[]`, or register a [webhook](/reference/create-a-webhook); each leg fires its own events with the same order id. ## Important notes - **Hub selection is automatic** — you request hub transit; we pick the hub. You can't specify one. - **One estimate, both legs** — a hub estimate's `estimate_id` and `line_items` represent the clearance leg with the local leg folded in. You never accept the local leg yourself. - **Availability is lane-dependent** — not every origin → destination has a serviceable hub; handle the `422 "No hub is available for this route."` response. - **Same order endpoint** — hub vs direct is decided entirely at quote time. Ordering is identical; you just use a hub estimate's id. --- # Taxes and duties Get the import VAT and import duties a shipment will attract, alongside the freight cost. ## What you get When we estimate taxes and duties, two extra line items appear in the estimate's `line_items`: | Description | What it is | |---|---| | `Import Duties` | Customs duty payable on the goods entering the destination country | | `Import VAT` | Import VAT / GST payable on the import into the destination country | They sit alongside `Base Rate`, `Fuel Surcharge` and the rest, in the same currency, so the estimate total is the landed cost rather than the freight cost. These are **estimates**. They are calculated from the HS codes you supply and the destination's tariff schedule, and the amount customs actually assesses can differ. We estimate again when the order is placed and again if the goods are re-declared. ## Asking for them on a quote Set `estimate_taxes_and_duties: true` on [Create a quote](/reference/create-a-quote), and send `hs_codes`. ```json { "estimate_taxes_and_duties": true, "purpose_of_shipment_id": 8, "hs_codes": [ { "code": "8544429000", "description": "insulated copper cable, 2m, with connectors", "country_id": 226, "quantity": 10, "weight": 0.4, "cost": 12.50 } ] } ``` The response echoes `estimate_taxes_and_duties` back, so you can confirm the request was honoured: ```json { "quote": { "id": 1, "estimate_taxes_and_duties": true, "estimates": [ { "estimate_id": 55788, "shipping_company": "DHL Express", "line_items": [ { "description": "Base Rate", "cost": 920.00, "currency_id": "USD" }, { "description": "Fuel Surcharge", "cost": 138.00, "currency_id": "USD" }, { "description": "Import Duties", "cost": 46.75, "currency_id": "USD" }, { "description": "Import VAT", "cost": 220.31, "currency_id": "USD" } ] } ] } } ``` The default is `false`. Omit it and you get a freight-only quote, exactly as before — **existing integrations are unaffected**. ## HS code fields `hs_codes` is an array, and takes the same fields on [Create a quote](/reference/create-a-quote) and [Create an order](/reference/create-an-order). | Field | Type | Required | Description | |-------|------|----------|-------------| | `code` | string | Yes | The HS / commodity code — see [Code length matters](#code-length-matters) | | `description` | string | Yes | Plain description of the goods, max 250 characters | | `country_id` | integer | Yes | Country of **manufacture**, not of origin or destination | | `weight` | number | Yes | Mass of **one unit**, in the request's `mass_unit` | | `quantity` | number | No | Number of units on this line | | `cost` | number | No | Value of **one unit**, in the request's `value_of_goods_currency_id` | | `eccn` | string | No | Export Control Classification Number, where one applies | | `nature_of_transaction` | string | No | EU nature-of-transaction code | `weight` and `cost` are **per unit**, not line totals. A line of 10 cables at 0.4 kg each is `quantity: 10, weight: 0.4` — not `weight: 4`. `item_mass` and `item_value` are accepted as synonyms for `weight` and `cost`. ## When you will get nothing back Estimation is skipped silently — no error, just no `Import VAT` or `Import Duties` line items. Every one of these must hold: 1. **The shipment must clear customs.** Skipped when the route is intra-EU, domestic (same origin and destination country), between the US and Puerto Rico, or when `is_document: true`. 2. **The incoterm must make you liable.** Only `DDP`, `EXW`, `FOB` and `FCA` qualify. On `DAP` / `DDU` the consignee settles with customs directly, so we don't estimate. 3. **You must send `hs_codes`.** The calculation is driven off them. 4. **The value must exceed the destination's de minimis threshold.** Below it, no VAT or duty is due and nothing is returned. The exception is goods manufactured in China entering the US, where de minimis never applies. Two further cases return duties but **no VAT**: - Your company holds a **VAT deferment** for the destination country, so import VAT is settled through your own arrangement rather than billed by us. - The `reason_for_shipment_id` is a return, a temporary export or import, or mutilated samples — these waive clearance charges, and waive **both** VAT and duties. > A document shipment never clears customs, so it never attracts VAT or duties, whatever the incoterm and whatever you send. If you are getting freight-only estimates on a `DDP` lane, check this field first. ### Code length matters We don't reject a short code, and that is the trap. Destinations tariff on a specific number of digits — commonly eight or ten, six at the least. A code shorter than the destination requires still returns an estimate, but a **less accurate** one, and it is the single biggest source of an estimate that does not match the customs bill. Send the full code your destination expects. Six digits is the shortest that carries any tariff meaning; anything below that is close to a guess. ## Taxes and duties on orders **Orders estimate taxes and duties automatically.** There is no field to set on [Create an order](/reference/create-an-order) and nothing to opt into — when the order is placed, we estimate against the same four conditions above and add the charges if they apply. This means a quote requested **without** `estimate_taxes_and_duties` can still become an order that carries import VAT and duties. The freight-only quote was never the landed cost, it just did not say so. Quote with `estimate_taxes_and_duties: true` when you need to show a customer the full cost up front. The charges appear on [Get an order](/reference/get-an-order) under `invoice_data.line_items`, with the same `Import Duties` and `Import VAT` descriptions. --- # Stream API The Stream API lets your own system do what your team does in the client portal: price a shipment with each carrier, book it, get the carrier's waybill, book the collection and follow the shipment to delivery. We can also tell your system when a shipment changes, through webhooks. Every example on the reference pages is one the API really sent, recorded by the API's own tests, so what you read is what you get back. The guides' examples are shortened and use made-up prices. Reference pages show each call in the language you pick on the site. ## Environments | Environment | Base URL | Use it for | |---|---|---| | Sandbox | `https://sandbox-api.vatit-stream.com/client_api/v2` | Building and testing. The carriers are stand-ins, so nothing is really shipped or charged. | | Production | `https://orders-production.vatit-stream.com/client_api/v2` | Real shipments. | The two environments have separate logins and separate data. Build against the sandbox first, then switch the base URL and your login when you go live. ## Making requests - Every request goes over **HTTPS**, and sends and receives **JSON**. Send `Content-Type: application/json` with a body. - [Sign in](/authentication) once for a token, then send it on every other call as `Authorization: Bearer `. - Ids are numbers. Take the ids a call needs, such as a country or a purpose of shipment, from the [reference data](/reference/reference-data) calls. ## Your first shipment 1. [Sign in](/reference/sign-in) for a token. 2. [Create a quote](/reference/create-a-quote): describe the shipment, and we price it with each carrier that can take it. 3. [Create an order](/reference/create-an-order) from the estimate you choose. 4. [Create a waybill](/reference/create-a-waybill) once the order's documents are in. 5. [List pickup slots](/reference/list-pickup-slots), then [book a pickup](/reference/book-a-pickup). 6. Follow the shipment with [Get an order](/reference/get-an-order) and [List tracking events](/reference/list-tracking-events), or have us call you with a [webhook](/reference/create-a-webhook). ## Conventions **Errors.** Every error has the same shape, `{ "success": false, "error": "...", "errors": [...] }`. See [Errors](/errors). **Dates and times.** All times are UTC. Most dates come as `YYYY/MM/DD HH:MM:SS UTC`, for example `2026/10/23 07:14:46 UTC`. The exceptions: | Field | Format | |---|---| | A pickup's `scheduled_date` | `YYYY/MM/DD HH:MM:SS UTC`, but the time is always midnight, so read only the date | | A pickup's `time_from` and `time_to` | `HH:MM:SS` | | An order's `pickup_date` | `YYYY-MM-DD` | | Webhook payloads | ISO 8601, for example `2026-10-23T07:14:46Z` | **Pages.** [List orders](/reference/list-orders) answers ten orders at a time, newest first. Ask for another page with `?page=2`, or for more per page with `?items_per_page=50`. The answer's `meta` gives `page_count` and `record_count`. **Rate limits.** [Create a quote](/reference/create-a-quote), [Create an order](/reference/create-an-order) and the [Companies](/reference/companies) calls take 20 requests a minute. Past that they answer `429` until the minute is up. **Retries.** Don't retry [Create a waybill](/reference/create-a-waybill) after a timeout: the first request may still be booking with the carrier. Read the order first, and call again only if it has no waybill. ## For AI tools Every page has a Markdown version: add `.md` to its address, or use **Copy for LLM** at the top of the page. [`/llms.txt`](/llms.txt) lists every page, and [`/llms-full.txt`](/llms-full.txt) has all of them in one file. The [OpenAPI file](/openapi/client-api.yaml) describes every call. --- # Authentication Sign in and get the token every other call needs. - [Sign in](https://docs.vatit-stream.com/reference/sign-in.md): `POST /client_api/v2/auth/sign_in` --- # Quotes Price a shipment with each carrier before you book it. - [Create a quote](https://docs.vatit-stream.com/reference/create-a-quote.md): `POST /client_api/v2/quotes` - [Get a quote](https://docs.vatit-stream.com/reference/get-a-quote.md): `GET /client_api/v2/quotes/{id}` --- # Orders Book a shipment from a quote, list and read your orders, and cancel one before it goes live. - [List orders](https://docs.vatit-stream.com/reference/list-orders.md): `GET /client_api/v2/orders` - [Create an order](https://docs.vatit-stream.com/reference/create-an-order.md): `POST /client_api/v2/orders` - [Cancel an order](https://docs.vatit-stream.com/reference/cancel-an-order.md): `DELETE /client_api/v2/orders/{id}` - [Get an order](https://docs.vatit-stream.com/reference/get-an-order.md): `GET /client_api/v2/orders/{id}` - [List order ids by status](https://docs.vatit-stream.com/reference/list-order-ids-by-status.md): `GET /client_api/v2/orders_by_status` --- # Waybills and pickups Get the carrier's waybill, see when the carrier can collect, and book the collection. - [List pickup slots](https://docs.vatit-stream.com/reference/list-pickup-slots.md): `GET /client_api/v2/orders/{order_id}/pickup_availabilities` - [List pickups](https://docs.vatit-stream.com/reference/list-pickups.md): `GET /client_api/v2/orders/{order_id}/schedule_pickups` - [Book a pickup](https://docs.vatit-stream.com/reference/book-a-pickup.md): `POST /client_api/v2/orders/{order_id}/schedule_pickups` - [Create a waybill](https://docs.vatit-stream.com/reference/create-a-waybill.md): `POST /client_api/v2/orders/{order_id}/waybills` --- # Tracking Follow a shipment's progress, as the carrier reports it. - [List tracking events](https://docs.vatit-stream.com/reference/list-tracking-events.md): `GET /client_api/v2/orders/{order_id}/tracking` --- # Companies For resellers. Set up the client companies you ship for, and list them. - [List companies](https://docs.vatit-stream.com/reference/list-companies.md): `GET /client_api/v2/companies` - [Create a company](https://docs.vatit-stream.com/reference/create-a-company.md): `POST /client_api/v2/companies` --- # Webhooks Have us tell your system when a shipment changes, instead of asking. - [Create a webhook](https://docs.vatit-stream.com/reference/create-a-webhook.md): `POST /client_api/v2/webhooks` - [Delete a webhook](https://docs.vatit-stream.com/reference/delete-a-webhook.md): `DELETE /client_api/v2/webhooks/{id}` - [Get a webhook](https://docs.vatit-stream.com/reference/get-a-webhook.md): `GET /client_api/v2/webhooks/{id}` - [Update a webhook](https://docs.vatit-stream.com/reference/update-a-webhook.md): `PUT /client_api/v2/webhooks/{id}` --- # Reference data The lists other calls take their ids and codes from. - [List countries](https://docs.vatit-stream.com/reference/list-countries.md): `GET /client_api/v2/countries` - [List currencies](https://docs.vatit-stream.com/reference/list-currencies.md): `GET /client_api/v2/currencies` - [List line item types](https://docs.vatit-stream.com/reference/list-line-item-types.md): `GET /client_api/v2/line_item_types` - [List natures of transaction](https://docs.vatit-stream.com/reference/list-natures-of-transaction.md): `GET /client_api/v2/nature_of_transactions` - [List order statuses](https://docs.vatit-stream.com/reference/list-order-statuses.md): `GET /client_api/v2/order_statuses` - [List purposes of shipment](https://docs.vatit-stream.com/reference/list-purposes-of-shipment.md): `GET /client_api/v2/purpose_of_shipments` - [List reasons for shipment](https://docs.vatit-stream.com/reference/list-reasons-for-shipment.md): `GET /client_api/v2/reason_for_shipments` - [Get a setting](https://docs.vatit-stream.com/reference/get-a-setting.md): `GET /client_api/v2/system_configs/{id}` --- # Sign in `POST /client_api/v2/auth/sign_in` Swap a login's email and password for a token. Send the token as a bearer token on every other call. It lasts a week. Needs no token. ## Body - `api_user` (object, required): The login to sign in with. - `email` (string, required): The login's email address. - `password` (string, required): The login's password. ## Returns Returns the token. - `token` (string, required): The token to send as `Authorization: Bearer ` on every other call. It lasts a week. ## Errors - `401 Unauthorized`: The token is missing, expired or invalid. Sign in again. ## Example request (curl) ```bash curl -X POST "https://sandbox-api.vatit-stream.com/client_api/v2/auth/sign_in" \ -H "Content-Type: application/json" \ -d '{ "api_user": { "email": "integrations@globaltradecorp.example", "password": "your-password" } }' ``` ## Example response (200) ```json { "token": "eyJhbGciOiJIUzI1NiJ9.eyJlbWFpbCI6ImludGVncmF0aW9uc0BnbG9iYWx0cmFkZWNvcnAuZXhhbXBsZSIsInN1YiI6IjkiLCJzY3AiOiJhcGlfdXNlciIsImF1ZCI6bnVsbCwiaWF0IjoxNzkyNzM5Njg2LCJleHAiOiIxNzkzMzQ0NDg2IiwianRpIjoiM2YxYzJhOWUtNmI0ZC00ZThhLTljNzEtMGQ1ZThiMmY0YTE2In0.tQ3m0Yk9v1S7bT2n5Zq8Lw4HcXr6JdPaUeVgNiOfMhA" } ``` --- # List companies `GET /client_api/v2/companies` For resellers. The client companies you can see. ## Returns Returns a list of companies. - `companies` (array of objects, required): The companies on this page. - `id` (integer, required): The company's id. - `account_number` (string, required): The company's account number. Order reference numbers start with it. - `account_status` (enum, required): Whether the company can ship. A suspended or dormant company gets no waybills. Possible enum values: `active`, `suspended`, `dormant`. - `address` (object, required): The company's address. - `id` (integer, required): The address's id. Send it as `origin_address_id` or `destination_address_id` to use the address again. - `address_1` (string, required): The street address. At most 34 characters. - `address_2` (string, nullable, required): A second address line, such as a floor or unit. At most 34 characters. - `address_3` (object, nullable, required): A third address line. - `city` (string, required): The city or town. At most 20 characters. - `classification` (enum, required): Whether the address is a business or a home. Carriers charge more to deliver to a home. Possible enum values: `business`, `residential`. - `company` (string, required): The company at the address. At most 35 characters. - `country_id` (integer, required): The country. Take the id from List countries. - `email` (string, required): An email address for the person at the address. Carriers use it for delivery notices. - `import_code` (object, nullable, required): The importer number of the party at the address. The country's `import_code_label` says what it is called there. - `latitude` (object, nullable, required): Where the address is, filled in by us shortly after the address is saved. Empty until then. - `longitude` (object, nullable, required): Where the address is, filled in by us shortly after the address is saved. Empty until then. - `name` (string, required): The person to ask for. At most 35 characters. - `phone` (string, required): A phone number for the person at the address. At most 15 characters. - `postal_code` (string, required): The postal code. Some countries, such as Ireland, refuse an address without one. - `province` (string, required): The province, state or county. - `summary` (string, required): The country's name. - `tax_number` (object, nullable, required): The tax or VAT number of the party at the address. The country's `tax_number_label` says what it is called there. - `time_zone_id` (object, nullable, required): The address's time zone, filled in by us shortly after the address is saved. Empty until then. - `api_users` (array of objects, required): The company's logins. - `id` (integer, required): The login's id. - `email` (string, required): The login's email address. - `identity` (string, required): The login's name, or its email address when it has no name. - `code` (string, required): The company's code with us, the same as its account number. - `company_billing` (boolean, required): `true` when we invoice the company directly, `false` when we invoice you as its reseller. - `currency_id` (string, required): The currency the company is billed in. - `name` (string, required): The company's name. - `meta` (object, required): How many pages and records the list has. - `page_count` (integer, required): How many pages the list has. Ask for another with `?page=`. - `record_count` (integer, required): How many records the list has across all pages. ## Errors - `401 Unauthorized`: The token is missing, expired or invalid. Sign in again. ## Example request (curl) ```bash curl -X GET "https://sandbox-api.vatit-stream.com/client_api/v2/companies" \ -H "Authorization: Bearer $API_TOKEN" ``` ## Example response (200) ```json { "companies": [ { "id": 9, "account_number": "MYSGLO001", "account_status": "active", "address": { "id": 143, "address_1": "14 Bree Street", "address_2": "Unit 3", "address_3": null, "city": "Cape Town", "classification": "business", "company": "Global Trade Corp", "country_id": 20, "email": "dispatch@globaltradecorp.example", "import_code": null, "latitude": null, "longitude": null, "name": "Thandi Mokoena", "phone": "+27215550142", "postal_code": "8001", "province": "Western Cape", "summary": "South Africa", "tax_number": null, "time_zone_id": null }, "api_users": [ { "id": 13, "email": "integrations@globaltradecorp.example", "identity": "Thandi Mokoena" } ], "code": "MYSGLO001", "company_billing": true, "currency_id": "ZAR", "name": "Global Trade Corp" }, { "id": 10, "account_number": "MYSKAR001", "account_status": "active", "address": { "id": 146, "address_1": "8 Church Street", "address_2": null, "address_3": null, "city": "Prince Albert", "classification": "business", "company": "Karoo Leather Works", "country_id": 20, "email": "pieter@karooleather.example", "import_code": null, "latitude": null, "longitude": null, "name": "Pieter van Wyk", "phone": "+27235550198", "postal_code": "6930", "province": "Western Cape", "summary": "South Africa", "tax_number": null, "time_zone_id": null }, "api_users": [ { "id": 14, "email": "admin@karooleather.example", "identity": "admin@karooleather.example" } ], "code": "MYSKAR001", "company_billing": true, "currency_id": "ZAR", "name": "Karoo Leather Works" } ], "meta": { "page_count": 1, "record_count": 2 } } ``` --- # Create a company `POST /client_api/v2/companies` For resellers. Sets up a client company under your reseller account, and a login for it when you send an email. ## Body - `name` (string, required): The company's name. It has to be unique across our accounts. - `email` (string): The email for the company's own API and portal login. Left out, no login is made. - `password` (string): The password for that login. Left out, we make one up. - `contact_name` (string): The person we talk to at the company. - `contact_email` (string): That person's email address. - `contact_number` (string): That person's phone number. - `currency_id` (string, required): The currency the company is billed in, as a three-letter code from List currencies. - `industry` (enum): What the company does. Possible enum values: `aerospace_defense`, `airlines_aviation`, `apparel_fashion`, `arts_crafts`, `automotive`, `aviation_aerospace`, `broadcast_media`, `chemicals`, `civil_engineering`, `computer_hardware`, `computer_software`, `construction`, `consumer_electronics`, `consumer_goods`, `defense_space`, `electrical_electronic_manufacturing`, `entertainment`, `events_services`, `fine_art`, `food_beverages`, `furniture`, `health_wellness_fitness`, `healthcare_services`, `hospital_health_care`, `industrial_automation`, `information_technology_and_services`, `investment_management`, `leisure_travel_tourism`, `logistics_supply_chain`, `luxury_goods_jewelry`, `machinery`, `manufacturing`, `mechanical_or_industrial_engineering`, `medical_devices`, `oil_energy`, `package_freight_delivery`, `paper_forest_products`, `pharmaceuticals`, `photography`, `printing`, `professional_training_coaching`, `publishing`, `retail`, `sporting_goods`, `telecommunications`, `textiles`, `transportation_trucking_railroad`, `utilities`, `wireless`, `other`. - `markup_multiplier` (number): What the company pays as a multiple of our price to you. `1.5` adds 50%. - `address_attributes` (object, required): The company's address. Its country decides which bank details the company's invoices show. - `name` (string): The person to ask for. At most 35 characters. - `company` (string): The company at the address. At most 35 characters. - `address_1` (string): The street address. At most 34 characters. - `city` (string): The city or town. At most 20 characters. - `province` (string): The province, state or county. - `postal_code` (string): The postal code. Some countries, such as Ireland, refuse an address without one. - `country_id` (integer, required): The country. Take the id from List countries. Ids differ between the sandbox and production. - `email` (string): An email address for the person at the address. Carriers use it for delivery notices. - `phone` (string): A phone number for the person at the address. At most 15 characters. ## Returns Returns the company. - `company` (object, required): The company. - `id` (integer, required): The company's id. - `account_number` (string, required): The company's account number. Order reference numbers start with it. - `account_status` (enum, required): Whether the company can ship. A suspended or dormant company gets no waybills. Possible enum values: `active`, `suspended`, `dormant`. - `address` (object, required): The company's address. - `id` (integer, required): The address's id. Send it as `origin_address_id` or `destination_address_id` to use the address again. - `address_1` (string, required): The street address. At most 34 characters. - `address_2` (object, nullable, required): A second address line, such as a floor or unit. At most 34 characters. - `address_3` (object, nullable, required): A third address line. - `city` (string, required): The city or town. At most 20 characters. - `classification` (enum, required): Whether the address is a business or a home. Carriers charge more to deliver to a home. Possible enum values: `business`, `residential`. - `company` (string, required): The company at the address. At most 35 characters. - `country_id` (integer, required): The country. Take the id from List countries. - `email` (string, required): An email address for the person at the address. Carriers use it for delivery notices. - `import_code` (object, nullable, required): The importer number of the party at the address. The country's `import_code_label` says what it is called there. - `latitude` (object, nullable, required): Where the address is, filled in by us shortly after the address is saved. Empty until then. - `longitude` (object, nullable, required): Where the address is, filled in by us shortly after the address is saved. Empty until then. - `name` (string, required): The person to ask for. At most 35 characters. - `phone` (string, required): A phone number for the person at the address. At most 15 characters. - `postal_code` (string, required): The postal code. Some countries, such as Ireland, refuse an address without one. - `province` (string, required): The province, state or county. - `summary` (string, required): The country's name. - `tax_number` (object, nullable, required): The tax or VAT number of the party at the address. The country's `tax_number_label` says what it is called there. - `time_zone_id` (object, nullable, required): The address's time zone, filled in by us shortly after the address is saved. Empty until then. - `api_users` (array of objects, required): The company's logins. - `id` (integer, required): The login's id. - `email` (string, required): The login's email address. - `identity` (string, required): The login's name, or its email address when it has no name. - `code` (string, required): The company's code with us, the same as its account number. - `company_billing` (boolean, required): `true` when we invoice the company directly, `false` when we invoice you as its reseller. - `currency_id` (string, required): The currency the company is billed in. - `name` (string, required): The company's name. ## Errors - `400 Bad Request`: The request body isn't valid JSON, or something failed on our side. - `401 Unauthorized`: The token is missing, expired or invalid. Sign in again. ## Example request (curl) ```bash curl -X POST "https://sandbox-api.vatit-stream.com/client_api/v2/companies" \ -H "Authorization: Bearer $API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Karoo Leather Works", "email": "admin@karooleather.example", "password": "choose-a-password", "contact_name": "Pieter van Wyk", "contact_email": "pieter@karooleather.example", "contact_number": "+27 23 555 0198", "currency_id": "ZAR", "industry": "consumer_goods", "markup_multiplier": 1.5, "address_attributes": { "name": "Pieter van Wyk", "company": "Karoo Leather Works", "address_1": "8 Church Street", "city": "Prince Albert", "province": "Western Cape", "postal_code": "6930", "country_id": 20, "email": "pieter@karooleather.example", "phone": "+27 23 555 0198" } }' ``` ## Example response (201) ```json { "company": { "id": 11, "account_number": "MYSKAR001", "account_status": "active", "address": { "id": 147, "address_1": "8 Church Street", "address_2": null, "address_3": null, "city": "Prince Albert", "classification": "business", "company": "Karoo Leather Works", "country_id": 20, "email": "pieter@karooleather.example", "import_code": null, "latitude": null, "longitude": null, "name": "Pieter van Wyk", "phone": "+27235550198", "postal_code": "6930", "province": "Western Cape", "summary": "South Africa", "tax_number": null, "time_zone_id": null }, "api_users": [ { "id": 15, "email": "admin@karooleather.example", "identity": "admin@karooleather.example" } ], "code": "MYSKAR001", "company_billing": true, "currency_id": "ZAR", "name": "Karoo Leather Works" } } ``` --- # List countries `GET /client_api/v2/countries` Every country, with its id for addresses and the labels its customs numbers go by. Needs no token. Needs no token. ## Parameters - `q` (string): Only countries whose name contains this text, in any case. ## Returns Returns a list of countries. - `countries` (array of objects, required): The countries on this page, by name. - `id` (integer, required): The country's id, for an address's `country_id`. - `default_postal_code` (object, nullable, required): The postal code we give the carrier for an address in this country that has none. - `dhl_export_code` (object, nullable, required): DHL's export code for the country. Usually empty. - `dhl_import_code` (object, nullable, required): DHL's import code for the country. Usually empty. - `dhl_tax_code` (object, nullable, required): DHL's tax code for the country. Usually empty. - `export_code_label` (string, required): What the country calls an exporter number. - `import_code_label` (string, required): What the country calls an importer number. - `iso_code_2` (string, required): The two-letter ISO code, such as `GB`. - `iso_code_3` (string, required): The three-letter ISO code, such as `GBR`. - `maximum_duty_rate` (number, required): The highest customs duty rate the country charges, as a fraction. - `name` (string, required): The country's name in English. - `part_of_eu_union` (boolean, required): `true` for a member of the European Union. - `postal_code_required` (boolean, required): `false` for the countries that have no postal codes. - `signed_civil_aircraft_agreement` (boolean, required): `true` for a signatory of the WTO Agreement on Trade in Civil Aircraft, an EU member included. Civil aircraft parts cross between signatories duty free. - `tax_number_label` (string, required): What the country calls a tax number. - `vat_rate` (number, required): The country's standard VAT or sales tax rate, as a fraction. `0.15` is 15%. - `meta` (object, required): How many pages and records the list has. - `page_count` (integer, required): How many pages the list has. Ask for another with `?page=`. - `record_count` (integer, required): How many records the list has across all pages. ## Example request (curl) ```bash curl -X GET "https://sandbox-api.vatit-stream.com/client_api/v2/countries?q=United" ``` ## Example response (200) ```json { "countries": [ { "id": 16, "default_postal_code": null, "dhl_export_code": null, "dhl_import_code": null, "dhl_tax_code": null, "export_code_label": "Export Number", "import_code_label": "Importer Code", "iso_code_2": "GB", "iso_code_3": "GBR", "maximum_duty_rate": 0.5, "name": "United Kingdom", "part_of_eu_union": false, "postal_code_required": true, "signed_civil_aircraft_agreement": true, "tax_number_label": "Tax Number", "vat_rate": 0.17 } ], "meta": { "page_count": 1, "record_count": 1 } } ``` --- # List currencies `GET /client_api/v2/currencies` The currencies we price in. Needs no token. Needs no token. ## Parameters - `show_all` (boolean): Send `true` to get every currency on one page. ## Returns Returns a list of currencies. - `currencies` (array of objects, required): The currencies on this page, by code. - `id` (string, required): The currency's three-letter code, the same as `code`. - `code` (string, required): The currency's three-letter ISO code, such as `ZAR`. - `name` (string, required): The currency's name. - `meta` (object, required): How many pages and records the list has. - `page_count` (integer, required): How many pages the list has. Ask for another with `?page=`. - `record_count` (integer, required): How many records the list has across all pages. ## Example request (curl) ```bash curl -X GET "https://sandbox-api.vatit-stream.com/client_api/v2/currencies?show_all=true" ``` ## Example response (200) ```json { "currencies": [ { "id": "CAD", "code": "CAD", "name": "Canadian Dollar" }, { "id": "EUR", "code": "EUR", "name": "Euro" }, { "id": "GBP", "code": "GBP", "name": "Pound" }, { "id": "USD", "code": "USD", "name": "Dollar" }, { "id": "ZAR", "code": "ZAR", "name": "Rand" } ], "meta": { "page_count": 1, "record_count": 5 } } ``` --- # List line item types `GET /client_api/v2/line_item_types` The kinds of charge an estimate's line items can be. ## Returns Returns a list of line item types. - `line_item_types` (array of objects, required): Every line item type. - `id` (integer, required): The line item type's id. - `accounting_dimension` (object, nullable, required): The accounting group we book this charge under. Usually empty. - `description` (string, required): The kind of charge, such as freight. ## Errors - `401 Unauthorized`: The token is missing, expired or invalid. Sign in again. ## Example request (curl) ```bash curl -X GET "https://sandbox-api.vatit-stream.com/client_api/v2/line_item_types" \ -H "Authorization: Bearer $API_TOKEN" ``` ## Example response (200) ```json { "line_item_types": [ { "id": 16, "accounting_dimension": null, "description": "Freight" } ] } ``` --- # List natures of transaction `GET /client_api/v2/nature_of_transactions` The customs codes for the kind of deal behind a declared item, such as a sale or a return. ## Returns Returns a list of nature of transactions. - `nature_of_transactions` (array of objects, required): Every nature of transaction. - `code` (enum, required): The two-digit customs code for the kind of deal. Possible enum values: `11`, `12`, `21`, `22`, `23`, `31`, `32`, `33`, `34`, `41`, `42`, `51`, `52`, `71`, `72`, `80`, `91`, `99`. - `description` (string, required): What the code means. - `label` (string, required): The code and its meaning together, for showing in a list. ## Errors - `401 Unauthorized`: The token is missing, expired or invalid. Sign in again. ## Example request (curl) ```bash curl -X GET "https://sandbox-api.vatit-stream.com/client_api/v2/nature_of_transactions" \ -H "Authorization: Bearer $API_TOKEN" ``` ## Example response (200) ```json { "nature_of_transactions": [ { "code": "11", "description": "Outright sale/purchase except direct trade with/by private consumers", "label": "11 - Outright sale/purchase except direct trade with/by private consumers" }, { "code": "12", "description": "Direct trade with/by private consumers (incl. distance selling)", "label": "12 - Direct trade with/by private consumers (incl. distance selling)" }, { "code": "21", "description": "Return of goods", "label": "21 - Return of goods" }, { "code": "22", "description": "Replacement for returned goods", "label": "22 - Replacement for returned goods" }, { "code": "23", "description": "Replacement for goods not being returned", "label": "23 - Replacement for goods not being returned" }, { "code": "31", "description": "Movements to/from a warehouse (excluding call-off and consignment stock)", "label": "31 - Movements to/from a warehouse (excluding call-off and consignment stock)" }, { "code": "32", "description": "Supply for sale on approval or after trial (incl. call-off and consignment stock)", "label": "32 - Supply for sale on approval or after trial (incl. call-off and consignment stock)" }, { "code": "33", "description": "Financial leasing", "label": "33 - Financial leasing" }, { "code": "34", "description": "Transactions involving transfer of ownership without financial compensation", "label": "34 - Transactions involving transfer of ownership without financial compensation" }, { "code": "41", "description": "Goods expected to return to the initial country of export", "label": "41 - Goods expected to return to the initial country of export" }, { "code": "42", "description": "Goods not expected to return to the initial country of export", "label": "42 - Goods not expected to return to the initial country of export" }, { "code": "51", "description": "Goods returning to the initial country of export", "label": "51 - Goods returning to the initial country of export" }, { "code": "52", "description": "Goods not returning to the initial country of export", "label": "52 - Goods not returning to the initial country of export" }, { "code": "71", "description": "Release of goods for free circulation in a Member State with subsequent export to another Member State", "label": "71 - Release of goods for free circulation in a Member State with subsequent export to another Member State" }, { "code": "72", "description": "Transportation of goods from one Member State to another to place them under the export procedure", "label": "72 - Transportation of goods from one Member State to another to place them under the export procedure" }, { "code": "80", "description": "Transactions involving the supply of building materials and equipment under a general construction or civil engineering contract", "label": "80 - Transactions involving the supply of building materials and equipment under a general construction or civil engineering contract" }, { "code": "91", "description": "Hire, loan and operational leasing longer than 24 months", "label": "91 - Hire, loan and operational leasing longer than 24 months" }, { "code": "99", "description": "Other transactions which cannot be classified under other codes", "label": "99 - Other transactions which cannot be classified under other codes" } ] } ``` --- # List order statuses `GET /client_api/v2/order_statuses` Every status an order or shipment can have. ## Returns Returns a list. - `id` (enum, required): The status, as it appears on an order or shipment. Possible enum values: `incomplete`, `order_received`, `awaiting_additional_documentation`, `awaiting_prepayment`, `awaiting_waybill_generation`, `awaiting_schedule_pickup`, `awaiting_pickup`, `awaiting_swap_out`, `pickup_missed`, `in_transit`, `partially_delivered`, `delivered`, `invoice_to_be_paid`, `invoice_paid`, `cancelled`, `lost_in_transit`, `awaiting_consolidation`, `consolidated`. - `description` (string, required): The status in words. - `value` (enum, required): The same as `id`. Possible enum values: `incomplete`, `order_received`, `awaiting_additional_documentation`, `awaiting_prepayment`, `awaiting_waybill_generation`, `awaiting_schedule_pickup`, `awaiting_pickup`, `awaiting_swap_out`, `pickup_missed`, `in_transit`, `partially_delivered`, `delivered`, `invoice_to_be_paid`, `invoice_paid`, `cancelled`, `lost_in_transit`, `awaiting_consolidation`, `consolidated`. ## Errors - `401 Unauthorized`: The token is missing, expired or invalid. Sign in again. ## Example request (curl) ```bash curl -X GET "https://sandbox-api.vatit-stream.com/client_api/v2/order_statuses" \ -H "Authorization: Bearer $API_TOKEN" ``` ## Example response (200) ```json [ { "id": "incomplete", "description": "Incomplete", "value": "incomplete" }, { "id": "order_received", "description": "Order received", "value": "order_received" }, { "id": "awaiting_additional_documentation", "description": "Awaiting additional documentation", "value": "awaiting_additional_documentation" }, { "id": "awaiting_prepayment", "description": "Awaiting prepayment", "value": "awaiting_prepayment" }, { "id": "awaiting_waybill_generation", "description": "Awaiting waybill generation", "value": "awaiting_waybill_generation" }, { "id": "awaiting_schedule_pickup", "description": "Awaiting schedule pickup", "value": "awaiting_schedule_pickup" }, { "id": "awaiting_pickup", "description": "Awaiting pickup", "value": "awaiting_pickup" }, { "id": "awaiting_swap_out", "description": "Awaiting swap out", "value": "awaiting_swap_out" }, { "id": "pickup_missed", "description": "Pickup missed", "value": "pickup_missed" }, { "id": "in_transit", "description": "In transit", "value": "in_transit" }, { "id": "partially_delivered", "description": "Partially delivered", "value": "partially_delivered" }, { "id": "delivered", "description": "Delivered", "value": "delivered" }, { "id": "invoice_to_be_paid", "description": "Invoice to be paid", "value": "invoice_to_be_paid" }, { "id": "invoice_paid", "description": "Invoice paid", "value": "invoice_paid" }, { "id": "cancelled", "description": "Cancelled", "value": "cancelled" }, { "id": "lost_in_transit", "description": "Lost in transit", "value": "lost_in_transit" }, { "id": "awaiting_consolidation", "description": "Awaiting consolidation", "value": "awaiting_consolidation" }, { "id": "consolidated", "description": "Consolidated", "value": "consolidated" } ] ``` --- # List orders `GET /client_api/v2/orders` Your company's orders, newest first, ten to a page unless you ask for more. Every filter is optional, and they combine. ## Parameters - `q` (string): Only orders whose waybill, reference number, customer reference or invoice number contains this text, or that were placed by a login whose email contains it, in any case. - `status` (string): Only orders with a shipment in this status, such as `in_transit`. List order statuses has every value. - `created_at_date_range_from` (string): The first day of a date range, as `YYYY-MM-DD`. With `created_at_date_range_to`, only orders created from this day to that one, both days included. Send both or neither. - `created_at_date_range_to` (string): The last day of the range, as `YYYY-MM-DD`. Send it with `created_at_date_range_from`. - `page` (integer): Which page to read, from 1. `meta.page_count` in the answer says how many pages there are. - `items_per_page` (integer): How many orders a page holds. 10 if you leave it out. ## Returns Returns a list of orders. - `orders` (array of objects, required): The orders on this page, newest first. - `id` (integer, required): The order's id, for every call about the order. - `assigned_admin` (object, nullable, required): The email address of the person on our team looking after the order. Empty until one is assigned. - `battery_declaration_link` (string, required): A link to download the battery declaration. Empty until there is one. - `broker_address` (object, nullable, required): The customs broker clearing the goods, when one is appointed. Empty otherwise. - `ccd_status` (enum, required): Where we stand on the destination's customs clearance document (CCD), for orders where we get one. Possible enum values: `ccd_not_required`, `ccd_required`, `voucher_of_correction_requested`, `voucher_of_correction_received`, `ccd_acquired`. - `commercial_invoice_link` (string, required): A link to download the commercial invoice. Empty until there is one. - `created_at` (string, required): When the order was placed, as `YYYY/MM/DD HH:MM:SS UTC`. - `customer_reference` (string, required): Your own reference for the order. - `customs_clearance_document_link` (string, required): A link to download the customs clearance document. Empty until there is one. - `date_delivered` (object, nullable, required): When the goods were delivered, as `YYYY/MM/DD HH:MM:SS UTC`. Empty until then. - `description_of_contents` (string, required): What is in the shipment. - `destination_address` (object, required): Where the goods are delivered. - `id` (integer, required): The address's id. Send it as `origin_address_id` or `destination_address_id` to use the address again. - `address_1` (string, required): The street address. At most 34 characters. - `address_2` (string, required): A second address line, such as a floor or unit. At most 34 characters. - `address_3` (object, nullable, required): A third address line. - `city` (string, required): The city or town. At most 20 characters. - `classification` (enum, required): Whether the address is a business or a home. Carriers charge more to deliver to a home. Possible enum values: `business`, `residential`. - `company` (string, required): The company at the address. At most 35 characters. - `country` (object, required): The country, in full. - `id` (integer, required): The country's id, for an address's `country_id`. - `default_postal_code` (object, nullable, required): The postal code we give the carrier for an address in this country that has none. - `dhl_export_code` (object, nullable, required): DHL's export code for the country. Usually empty. - `dhl_import_code` (object, nullable, required): DHL's import code for the country. Usually empty. - `dhl_tax_code` (object, nullable, required): DHL's tax code for the country. Usually empty. - `export_code_label` (string, required): What the country calls an exporter number. - `import_code_label` (string, required): What the country calls an importer number. - `iso_code_2` (string, required): The two-letter ISO code, such as `GB`. - `iso_code_3` (string, required): The three-letter ISO code, such as `GBR`. - `name` (string, required): The country's name in English. - `postal_code_required` (boolean, required): `false` for the countries that have no postal codes. - `tax_number_label` (string, required): What the country calls a tax number. - `vat_rate` (number, required): The country's standard VAT or sales tax rate, as a fraction. `0.15` is 15%. - `country_id` (integer, required): The country. Take the id from List countries. - `email` (string, required): An email address for the person at the address. Carriers use it for delivery notices. - `import_code` (object, nullable, required): The importer number of the party at the address. The country's `import_code_label` says what it is called there. - `latitude` (object, nullable, required): Where the address is, filled in by us shortly after the address is saved. Empty until then. - `longitude` (object, nullable, required): Where the address is, filled in by us shortly after the address is saved. Empty until then. - `name` (string, required): The person to ask for. At most 35 characters. - `phone` (string, required): A phone number for the person at the address. At most 15 characters. - `postal_code` (string, required): The postal code. Some countries, such as Ireland, refuse an address without one. - `province` (string, required): The province, state or county. - `summary` (string, required): The country's name. - `tax_number` (object, nullable, required): The tax or VAT number of the party at the address. The country's `tax_number_label` says what it is called there. - `time_zone_id` (object, nullable, required): The address's time zone, filled in by us shortly after the address is saved. Empty until then. - `draft_bill_of_lading_link` (string, required): A link to download the draft bill of lading. Empty until there is one. - `eei_eligible` (boolean, required): `true` when the shipment needs an Electronic Export Information filing with US customs. - `eei_request_document_link` (string, required): A link to download the export filing request. Empty until there is one. - `export_permit_link` (string, required): A link to download the export permit. Empty until there is one. - `final_bill_of_lading_link` (string, required): A link to download the final bill of lading. Empty until there is one. - `importer_of_record_address` (object, nullable, required): The importer of record, when the shipment has one. Empty otherwise. - `internal_transaction_number` (object, nullable, required): The US customs reference (ITN) for the export filing. Empty unless one was filed. - `invoice_data` (object, required): The booked estimate, with its weights and charges. Empty until an estimate is booked. - `billable_weights` (object, required): The weights the carrier charges on, in metric and in imperial units. - `metric` (object, required): The weights in kilograms, the sizes in centimetres and the volume in cubic metres. - `packages` (integer, required): How many packages there are. - `mass_unit` (string, required): Always `kg`. - `distance_unit` (string, required): Always `cm`. - `volumetric_weight` (number, required): The weight the carrier works out from the packages' size. - `weight` (number, required): What the packages weigh together. - `billable_weight` (number, required): The weight the carrier charges on, the larger of `weight` and `volumetric_weight`. - `volume` (number, required): The packages' volume together. - `imperial` (object, required): The weights in pounds, the sizes in inches and the volume in cubic feet. - `packages` (integer, required): How many packages there are. - `mass_unit` (string, required): Always `lb`. - `distance_unit` (string, required): Always `inches`. A request spells the same unit `inch`. - `volumetric_weight` (number, required): The weight the carrier works out from the packages' size. - `weight` (number, required): What the packages weigh together. - `billable_weight` (number, required): The weight the carrier charges on, the larger of `weight` and `volumetric_weight`. - `volume` (number, required): The packages' volume together. - `estimate_id` (integer, required): The estimate's id. Book it by sending it as an order's `quote_estimate_id`. - `line_items` (array of objects, required): What the price is made of, one charge per line. - `cost` (number, required): What the charge costs, in `currency_id`. - `currency_id` (string, required): The currency the company is billed in. - `description` (string, required): The charge, such as freight or fuel surcharge. - `quote_expired` (boolean, required): `true` when this price no longer holds, because another estimate was booked or the shipment changed. Get a new quote. - `shipping_company` (string, required): The carrier. - `shipping_service` (string, required): The carrier's service, such as International Priority. - `invoice_number` (object, nullable, required): Our invoice number for the order. Empty until we invoice it. - `materials_safety_data_sheet_link` (string, required): A link to download the materials safety data sheet. Empty until there is one. - `measured_weight` (number, required): What the carrier weighed the shipment at, in kilograms. `0` until the carrier weighs it. - `origin_address` (object, required): Where the carrier collects the goods. - `id` (integer, required): The address's id. Send it as `origin_address_id` or `destination_address_id` to use the address again. - `address_1` (string, required): The street address. At most 34 characters. - `address_2` (string, required): A second address line, such as a floor or unit. At most 34 characters. - `address_3` (object, nullable, required): A third address line. - `city` (string, required): The city or town. At most 20 characters. - `classification` (enum, required): Whether the address is a business or a home. Carriers charge more to deliver to a home. Possible enum values: `business`, `residential`. - `company` (string, required): The company at the address. At most 35 characters. - `country` (object, required): The country, in full. - `id` (integer, required): The country's id, for an address's `country_id`. - `default_postal_code` (object, nullable, required): The postal code we give the carrier for an address in this country that has none. - `dhl_export_code` (object, nullable, required): DHL's export code for the country. Usually empty. - `dhl_import_code` (object, nullable, required): DHL's import code for the country. Usually empty. - `dhl_tax_code` (object, nullable, required): DHL's tax code for the country. Usually empty. - `export_code_label` (string, required): What the country calls an exporter number. - `import_code_label` (string, required): What the country calls an importer number. - `iso_code_2` (string, required): The two-letter ISO code, such as `GB`. - `iso_code_3` (string, required): The three-letter ISO code, such as `GBR`. - `name` (string, required): The country's name in English. - `postal_code_required` (boolean, required): `false` for the countries that have no postal codes. - `tax_number_label` (string, required): What the country calls a tax number. - `vat_rate` (number, required): The country's standard VAT or sales tax rate, as a fraction. `0.15` is 15%. - `country_id` (integer, required): The country. Take the id from List countries. - `email` (string, required): An email address for the person at the address. Carriers use it for delivery notices. - `import_code` (object, nullable, required): The importer number of the party at the address. The country's `import_code_label` says what it is called there. - `latitude` (object, nullable, required): Where the address is, filled in by us shortly after the address is saved. Empty until then. - `longitude` (object, nullable, required): Where the address is, filled in by us shortly after the address is saved. Empty until then. - `name` (string, required): The person to ask for. At most 35 characters. - `phone` (string, required): A phone number for the person at the address. At most 15 characters. - `postal_code` (string, required): The postal code. Some countries, such as Ireland, refuse an address without one. - `province` (string, required): The province, state or county. - `summary` (string, required): The country's name. - `tax_number` (object, nullable, required): The tax or VAT number of the party at the address. The country's `tax_number_label` says what it is called there. - `time_zone_id` (object, nullable, required): The address's time zone, filled in by us shortly after the address is saved. Empty until then. - `packaging_list_link` (string, required): A link to download the packing list you uploaded. Empty until there is one. - `pickup_date` (object, nullable, required): The day the carrier collected the goods, as `YYYY-MM-DD`. Empty until then. - `pickup_instructions` (string, required): What the driver was told when the pickup was booked. Empty when none is booked. - `proof_of_delivery_link` (string, required): A link to download the proof of delivery. Empty until there is one. - `purpose_of_shipment_id` (integer, required): The incoterm the goods move under. - `quote_id` (integer, required): The quote the order was booked from. - `reference_number` (string, required): Our reference for the order, the one our team and the client portal use, for example `MYSGLO001000001`. - `scheduled_pickup` (string, required): The pickup booked for the order. An empty string, not an empty object, when none is booked. - `send_consignee_tracking_details` (boolean, required): `true` when the receiver is sent the tracking details. - `shipments` (array of objects, required): Each leg of the shipment, in route order. Most orders have one. - `shipping_service` (string, required): The carrier's service for this leg. - `status` (enum, required): Where this leg is. List order statuses has every value. Possible enum values: `incomplete`, `order_received`, `awaiting_additional_documentation`, `awaiting_prepayment`, `awaiting_waybill_generation`, `awaiting_schedule_pickup`, `awaiting_pickup`, `awaiting_swap_out`, `pickup_missed`, `in_transit`, `partially_delivered`, `delivered`, `invoice_to_be_paid`, `invoice_paid`, `cancelled`, `lost_in_transit`, `awaiting_consolidation`, `consolidated`. - `tracking_link` (object, nullable, required): The carrier's tracking page for this leg. Empty until there is a waybill. - `waybill` (object, nullable, required): The carrier's waybill number for this leg. Empty until there is one. - `waybill_document_link` (string, required): A link to download this leg's waybill. Empty until there is one. - `shippers_letter_of_instruction_link` (string, required): A link to download the shipper's letter of instruction. Empty until there is one. - `status` (enum, required): Where the shipment is. For an order with more than one leg, the last leg's status. List order statuses has every value. Possible enum values: `incomplete`, `order_received`, `awaiting_additional_documentation`, `awaiting_prepayment`, `awaiting_waybill_generation`, `awaiting_schedule_pickup`, `awaiting_pickup`, `awaiting_swap_out`, `pickup_missed`, `in_transit`, `partially_delivered`, `delivered`, `invoice_to_be_paid`, `invoice_paid`, `cancelled`, `lost_in_transit`, `awaiting_consolidation`, `consolidated`. - `stream_packing_list_link` (string, required): A link to download the packing list we made. Empty until there is one. - `tracking_link` (object, nullable, required): The carrier's tracking page for the shipment. Empty until there is a waybill. - `value_of_goods` (number, required): What the goods are worth in total. - `value_of_goods_currency` (string, required): The currency of `value_of_goods`, as a three-letter code. - `waybill` (object, nullable, required): The carrier's waybill number. Empty until Create a waybill has run. - `waybill_document_link` (string, required): A link to download the waybill. Empty until there is one. - `meta` (object, required): How many pages and records the list has. - `page_count` (integer, required): How many pages the list has. Ask for another with `?page=`. - `record_count` (integer, required): How many records the list has across all pages. ## Errors - `401 Unauthorized`: The token is missing, expired or invalid. Sign in again. ## Example request (curl) ```bash curl -X GET "https://sandbox-api.vatit-stream.com/client_api/v2/orders?q=GTC-PO-20417&status=order_received&created_at_date_range_from=2026-10-23&created_at_date_range_to=2026-10-23&page=1&items_per_page=10" \ -H "Authorization: Bearer $API_TOKEN" ``` ## Example response (200) ```json { "orders": [ { "id": 22, "assigned_admin": null, "battery_declaration_link": "", "broker_address": null, "ccd_status": "ccd_not_required", "commercial_invoice_link": "", "created_at": "2026/10/23 07:14:46 UTC", "customer_reference": "GTC-PO-20417", "customs_clearance_document_link": "", "date_delivered": null, "description_of_contents": "Cotton shirts and denim trousers", "destination_address": { "id": 104, "address_1": "221 Shoreditch High Street", "address_2": "Floor 2", "address_3": null, "city": "London", "classification": "business", "company": "Bennett & Hale Ltd", "country": { "id": 18, "default_postal_code": null, "dhl_export_code": null, "dhl_import_code": null, "dhl_tax_code": null, "export_code_label": "Export Number", "import_code_label": "Importer Code", "iso_code_2": "GB", "iso_code_3": "GBR", "name": "United Kingdom", "postal_code_required": true, "tax_number_label": "Tax Number", "vat_rate": 0.17 }, "country_id": 18, "email": "goods-in@bennetthale.example", "import_code": null, "latitude": null, "longitude": null, "name": "Oliver Bennett", "phone": "+442079460321", "postal_code": "E1 6PJ", "province": "Greater London", "summary": "United Kingdom", "tax_number": null, "time_zone_id": null }, "draft_bill_of_lading_link": "", "eei_eligible": false, "eei_request_document_link": "", "export_permit_link": "", "final_bill_of_lading_link": "", "importer_of_record_address": null, "internal_transaction_number": null, "invoice_data": { "billable_weights": { "metric": { "packages": 1, "mass_unit": "kg", "distance_unit": "cm", "volumetric_weight": 16.8, "weight": 12.5, "billable_weight": 16.8, "volume": 0.084 }, "imperial": { "packages": 1, "mass_unit": "lb", "distance_unit": "inches", "volumetric_weight": 37.04, "weight": 27.56, "billable_weight": 37.04, "volume": 2.9664316254643865 } }, "estimate_id": 17, "line_items": [ { "cost": 2184.5, "currency_id": "ZAR", "description": "Freight" }, { "cost": 393.21, "currency_id": "ZAR", "description": "Fuel surcharge" }, { "cost": 450, "currency_id": "ZAR", "description": "Customs clearance" } ], "quote_expired": false, "shipping_company": "FedEx South Africa", "shipping_service": "International Priority" }, "invoice_number": null, "materials_safety_data_sheet_link": "", "measured_weight": 0, "origin_address": { "id": 103, "address_1": "14 Bree Street", "address_2": "Unit 3", "address_3": null, "city": "Cape Town", "classification": "business", "company": "Global Trade Corp", "country": { "id": 17, "default_postal_code": null, "dhl_export_code": null, "dhl_import_code": null, "dhl_tax_code": null, "export_code_label": "Export Number", "import_code_label": "Importer Code", "iso_code_2": "ZA", "iso_code_3": "ZAF", "name": "South Africa", "postal_code_required": true, "tax_number_label": "Tax Number", "vat_rate": 0.17 }, "country_id": 17, "email": "dispatch@globaltradecorp.example", "import_code": null, "latitude": null, "longitude": null, "name": "Thandi Mokoena", "phone": "+27215550142", "postal_code": "8001", "province": "Western Cape", "summary": "South Africa", "tax_number": null, "time_zone_id": null }, "packaging_list_link": "", "pickup_date": null, "pickup_instructions": "", "proof_of_delivery_link": "", "purpose_of_shipment_id": 50, "quote_id": 22, "reference_number": "MYSGLO001000001", "scheduled_pickup": "", "send_consignee_tracking_details": false, "shipments": [ { "shipping_service": "International Priority", "status": "order_received", "tracking_link": null, "waybill": null, "waybill_document_link": "" } ], "shippers_letter_of_instruction_link": "", "status": "order_received", "stream_packing_list_link": "", "tracking_link": null, "value_of_goods": 18500, "value_of_goods_currency": "ZAR", "waybill": null, "waybill_document_link": "" } ], "meta": { "page_count": 1, "record_count": 1 } } ``` --- # Create an order `POST /client_api/v2/orders` Book one of a quote's estimates. The order starts as `order_received`; ask for its waybill next. ## Body - `order` (object, required): The order to place. - `quote_estimate_id` (integer, required): The estimate to book, from a quote's `estimates[].estimate_id`. - `purpose_of_shipment_id` (integer, required): The incoterm the goods move under. Take the id from List purposes of shipment. Ids differ between the sandbox and production. - `customer_reference` (string): Your own reference for the order, such as a purchase order number. We show it back on the order. - `description_of_contents` (string): What is in the shipment, in a few words a customs officer understands. Replaces the quote's description. At most 70 characters. - `origin_address` (object): The collection address in full. Wins over `origin_address_id` when both are sent. - `name` (string): The person to ask for. At most 35 characters. - `company` (string): The company at the address. At most 35 characters. - `address_1` (string): The street address. At most 34 characters. - `address_2` (string): A second address line, such as a floor or unit. At most 34 characters. - `city` (string): The city or town. At most 20 characters. - `province` (string): The province, state or county. - `postal_code` (string): The postal code. Some countries, such as Ireland, refuse an address without one. - `country_id` (integer, required): The country. Take the id from List countries. Ids differ between the sandbox and production. - `email` (string): An email address for the person at the address. Carriers use it for delivery notices. - `phone` (string): A phone number for the person at the address. At most 15 characters. - `classification` (enum): Whether the address is a business or a home. Carriers charge more to deliver to a home. Possible enum values: `business`, `residential`. - `destination_address` (object): The delivery address in full. Wins over `destination_address_id` when both are sent. - `name` (string): The person to ask for. At most 35 characters. - `company` (string): The company at the address. At most 35 characters. - `address_1` (string): The street address. At most 34 characters. - `address_2` (string): A second address line, such as a floor or unit. At most 34 characters. - `city` (string): The city or town. At most 20 characters. - `province` (string): The province, state or county. - `postal_code` (string): The postal code. Some countries, such as Ireland, refuse an address without one. - `country_id` (integer, required): The country. Take the id from List countries. Ids differ between the sandbox and production. - `email` (string): An email address for the person at the address. Carriers use it for delivery notices. - `phone` (string): A phone number for the person at the address. At most 15 characters. - `classification` (enum): Whether the address is a business or a home. Carriers charge more to deliver to a home. Possible enum values: `business`, `residential`. - `origin_address_id` (integer): The id of an address we already hold, to collect from instead of sending `origin_address`. - `destination_address_id` (integer): The id of an address we already hold, to deliver to instead of sending `destination_address`. ## Returns Returns the order. - `order` (object, required): The order. - `id` (integer, required): The order's id, for every call about the order. - `assigned_admin` (object, nullable, required): The email address of the person on our team looking after the order. Empty until one is assigned. - `battery_declaration_link` (string, required): A link to download the battery declaration. Empty until there is one. - `broker_address` (object, nullable, required): The customs broker clearing the goods, when one is appointed. Empty otherwise. - `ccd_status` (enum, required): Where we stand on the destination's customs clearance document (CCD), for orders where we get one. Possible enum values: `ccd_not_required`, `ccd_required`, `voucher_of_correction_requested`, `voucher_of_correction_received`, `ccd_acquired`. - `commercial_invoice_link` (string, required): A link to download the commercial invoice. Empty until there is one. - `created_at` (string, required): When the order was placed, as `YYYY/MM/DD HH:MM:SS UTC`. - `customer_reference` (string, nullable, required): Your own reference for the order. - `customs_clearance_document_link` (string, required): A link to download the customs clearance document. Empty until there is one. - `date_delivered` (object, nullable, required): When the goods were delivered, as `YYYY/MM/DD HH:MM:SS UTC`. Empty until then. - `description_of_contents` (string, nullable, required): What is in the shipment. - `destination_address` (object, required): Where the goods are delivered. - `id` (integer, required): The address's id. Send it as `origin_address_id` or `destination_address_id` to use the address again. - `address_1` (string, required): The street address. At most 34 characters. - `address_2` (string, required): A second address line, such as a floor or unit. At most 34 characters. - `address_3` (string, nullable, required): A third address line. - `city` (string, required): The city or town. At most 20 characters. - `classification` (enum, required): Whether the address is a business or a home. Carriers charge more to deliver to a home. Possible enum values: `business`, `residential`. - `company` (string, required): The company at the address. At most 35 characters. - `country` (object, required): The country, in full. - `id` (integer, required): The country's id, for an address's `country_id`. - `default_postal_code` (object, nullable, required): The postal code we give the carrier for an address in this country that has none. - `dhl_export_code` (object, nullable, required): DHL's export code for the country. Usually empty. - `dhl_import_code` (object, nullable, required): DHL's import code for the country. Usually empty. - `dhl_tax_code` (object, nullable, required): DHL's tax code for the country. Usually empty. - `export_code_label` (string, required): What the country calls an exporter number. - `import_code_label` (string, required): What the country calls an importer number. - `iso_code_2` (string, required): The two-letter ISO code, such as `GB`. - `iso_code_3` (string, required): The three-letter ISO code, such as `GBR`. - `name` (string, required): The country's name in English. - `postal_code_required` (boolean, required): `false` for the countries that have no postal codes. - `tax_number_label` (string, required): What the country calls a tax number. - `vat_rate` (number, required): The country's standard VAT or sales tax rate, as a fraction. `0.15` is 15%. - `country_id` (integer, required): The country. Take the id from List countries. - `email` (string, required): An email address for the person at the address. Carriers use it for delivery notices. - `import_code` (string, nullable, required): The importer number of the party at the address. The country's `import_code_label` says what it is called there. - `latitude` (object, nullable, required): Where the address is, filled in by us shortly after the address is saved. Empty until then. - `longitude` (object, nullable, required): Where the address is, filled in by us shortly after the address is saved. Empty until then. - `name` (string, required): The person to ask for. At most 35 characters. - `phone` (string, required): A phone number for the person at the address. At most 15 characters. - `postal_code` (string, required): The postal code. Some countries, such as Ireland, refuse an address without one. - `province` (string, required): The province, state or county. - `summary` (string, required): The country's name. - `tax_number` (object, nullable, required): The tax or VAT number of the party at the address. The country's `tax_number_label` says what it is called there. - `time_zone_id` (object, nullable, required): The address's time zone, filled in by us shortly after the address is saved. Empty until then. - `draft_bill_of_lading_link` (string, required): A link to download the draft bill of lading. Empty until there is one. - `eei_eligible` (boolean, required): `true` when the shipment needs an Electronic Export Information filing with US customs. - `eei_request_document_link` (string, required): A link to download the export filing request. Empty until there is one. - `export_permit_link` (string, required): A link to download the export permit. Empty until there is one. - `final_bill_of_lading_link` (string, required): A link to download the final bill of lading. Empty until there is one. - `importer_of_record_address` (object, nullable, required): The importer of record, when the shipment has one. Empty otherwise. - `internal_transaction_number` (object, nullable, required): The US customs reference (ITN) for the export filing. Empty unless one was filed. - `invoice_data` (object, required): The booked estimate, with its weights and charges. Empty until an estimate is booked. - `billable_weights` (object, required): The weights the carrier charges on, in metric and in imperial units. - `metric` (object, required): The weights in kilograms, the sizes in centimetres and the volume in cubic metres. - `packages` (integer, required): How many packages there are. - `mass_unit` (string, required): Always `kg`. - `distance_unit` (string, required): Always `cm`. - `volumetric_weight` (number, required): The weight the carrier works out from the packages' size. - `weight` (number, required): What the packages weigh together. - `billable_weight` (number, required): The weight the carrier charges on, the larger of `weight` and `volumetric_weight`. - `volume` (number, required): The packages' volume together. - `imperial` (object, required): The weights in pounds, the sizes in inches and the volume in cubic feet. - `packages` (integer, required): How many packages there are. - `mass_unit` (string, required): Always `lb`. - `distance_unit` (string, required): Always `inches`. A request spells the same unit `inch`. - `volumetric_weight` (number, required): The weight the carrier works out from the packages' size. - `weight` (number, required): What the packages weigh together. - `billable_weight` (number, required): The weight the carrier charges on, the larger of `weight` and `volumetric_weight`. - `volume` (number, required): The packages' volume together. - `estimate_id` (integer, required): The estimate's id. Book it by sending it as an order's `quote_estimate_id`. - `line_items` (array of objects, required): What the price is made of, one charge per line. - `cost` (number, required): What the charge costs, in `currency_id`. - `currency_id` (string, required): The currency the company is billed in. - `description` (string, required): The charge, such as freight or fuel surcharge. - `quote_expired` (boolean, required): `true` when this price no longer holds, because another estimate was booked or the shipment changed. Get a new quote. - `shipping_company` (string, required): The carrier. - `shipping_service` (string, required): The carrier's service, such as International Priority. - `invoice_number` (object, nullable, required): Our invoice number for the order. Empty until we invoice it. - `materials_safety_data_sheet_link` (string, required): A link to download the materials safety data sheet. Empty until there is one. - `measured_weight` (number, required): What the carrier weighed the shipment at, in kilograms. `0` until the carrier weighs it. - `origin_address` (object, required): Where the carrier collects the goods. - `id` (integer, required): The address's id. Send it as `origin_address_id` or `destination_address_id` to use the address again. - `address_1` (string, required): The street address. At most 34 characters. - `address_2` (string, required): A second address line, such as a floor or unit. At most 34 characters. - `address_3` (string, nullable, required): A third address line. - `city` (string, required): The city or town. At most 20 characters. - `classification` (enum, required): Whether the address is a business or a home. Carriers charge more to deliver to a home. Possible enum values: `business`, `residential`. - `company` (string, required): The company at the address. At most 35 characters. - `country` (object, required): The country, in full. - `id` (integer, required): The country's id, for an address's `country_id`. - `default_postal_code` (object, nullable, required): The postal code we give the carrier for an address in this country that has none. - `dhl_export_code` (object, nullable, required): DHL's export code for the country. Usually empty. - `dhl_import_code` (object, nullable, required): DHL's import code for the country. Usually empty. - `dhl_tax_code` (object, nullable, required): DHL's tax code for the country. Usually empty. - `export_code_label` (string, required): What the country calls an exporter number. - `import_code_label` (string, required): What the country calls an importer number. - `iso_code_2` (string, required): The two-letter ISO code, such as `GB`. - `iso_code_3` (string, required): The three-letter ISO code, such as `GBR`. - `name` (string, required): The country's name in English. - `postal_code_required` (boolean, required): `false` for the countries that have no postal codes. - `tax_number_label` (string, required): What the country calls a tax number. - `vat_rate` (number, required): The country's standard VAT or sales tax rate, as a fraction. `0.15` is 15%. - `country_id` (integer, required): The country. Take the id from List countries. - `email` (string, required): An email address for the person at the address. Carriers use it for delivery notices. - `import_code` (string, nullable, required): The importer number of the party at the address. The country's `import_code_label` says what it is called there. - `latitude` (object, nullable, required): Where the address is, filled in by us shortly after the address is saved. Empty until then. - `longitude` (object, nullable, required): Where the address is, filled in by us shortly after the address is saved. Empty until then. - `name` (string, required): The person to ask for. At most 35 characters. - `phone` (string, required): A phone number for the person at the address. At most 15 characters. - `postal_code` (string, required): The postal code. Some countries, such as Ireland, refuse an address without one. - `province` (string, required): The province, state or county. - `summary` (string, required): The country's name. - `tax_number` (object, nullable, required): The tax or VAT number of the party at the address. The country's `tax_number_label` says what it is called there. - `time_zone_id` (object, nullable, required): The address's time zone, filled in by us shortly after the address is saved. Empty until then. - `packaging_list_link` (string, required): A link to download the packing list you uploaded. Empty until there is one. - `pickup_date` (string, nullable, required): The day the carrier collected the goods, as `YYYY-MM-DD`. Empty until then. - `pickup_instructions` (string, required): What the driver was told when the pickup was booked. Empty when none is booked. - `proof_of_delivery_link` (string, required): A link to download the proof of delivery. Empty until there is one. - `purpose_of_shipment_id` (integer, required): The incoterm the goods move under. - `quote_id` (integer, required): The quote the order was booked from. - `reference_number` (string, required): Our reference for the order, the one our team and the client portal use, for example `MYSGLO001000001`. - `scheduled_pickup` (string, required): The pickup booked for the order. An empty string, not an empty object, when none is booked. - `send_consignee_tracking_details` (boolean, required): `true` when the receiver is sent the tracking details. - `shipments` (array of objects, required): Each leg of the shipment, in route order. Most orders have one. - `shipping_service` (string, required): The carrier's service for this leg. - `status` (enum, required): Where this leg is. List order statuses has every value. Possible enum values: `incomplete`, `order_received`, `awaiting_additional_documentation`, `awaiting_prepayment`, `awaiting_waybill_generation`, `awaiting_schedule_pickup`, `awaiting_pickup`, `awaiting_swap_out`, `pickup_missed`, `in_transit`, `partially_delivered`, `delivered`, `invoice_to_be_paid`, `invoice_paid`, `cancelled`, `lost_in_transit`, `awaiting_consolidation`, `consolidated`. - `tracking_link` (object, nullable, required): The carrier's tracking page for this leg. Empty until there is a waybill. - `waybill` (string, nullable, required): The carrier's waybill number for this leg. Empty until there is one. - `waybill_document_link` (string, required): A link to download this leg's waybill. Empty until there is one. - `shippers_letter_of_instruction_link` (string, required): A link to download the shipper's letter of instruction. Empty until there is one. - `status` (enum, required): Where the shipment is. For an order with more than one leg, the last leg's status. List order statuses has every value. Possible enum values: `incomplete`, `order_received`, `awaiting_additional_documentation`, `awaiting_prepayment`, `awaiting_waybill_generation`, `awaiting_schedule_pickup`, `awaiting_pickup`, `awaiting_swap_out`, `pickup_missed`, `in_transit`, `partially_delivered`, `delivered`, `invoice_to_be_paid`, `invoice_paid`, `cancelled`, `lost_in_transit`, `awaiting_consolidation`, `consolidated`. - `stream_packing_list_link` (string, required): A link to download the packing list we made. Empty until there is one. - `tracking_link` (object, nullable, required): The carrier's tracking page for the shipment. Empty until there is a waybill. - `value_of_goods` (number, required): What the goods are worth in total. - `value_of_goods_currency` (string, required): The currency of `value_of_goods`, as a three-letter code. - `waybill` (string, nullable, required): The carrier's waybill number. Empty until Create a waybill has run. - `waybill_document_link` (string, required): A link to download the waybill. Empty until there is one. ## Errors - `400 Bad Request`: The request body isn't valid JSON, or something failed on our side. - `401 Unauthorized`: The token is missing, expired or invalid. Sign in again. - `422 Unprocessable Content`: The request was refused. `error` says why in one sentence, and `errors` lists each reason. ## Example request (curl) ```bash curl -X POST "https://sandbox-api.vatit-stream.com/client_api/v2/orders" \ -H "Authorization: Bearer $API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "order": { "quote_estimate_id": 16, "purpose_of_shipment_id": 50, "customer_reference": "GTC-PO-20417", "description_of_contents": "Cotton shirts and denim trousers", "origin_address": { "name": "Thandi Mokoena", "company": "Global Trade Corp", "address_1": "14 Bree Street", "address_2": "Unit 3", "city": "Cape Town", "province": "Western Cape", "postal_code": "8001", "country_id": 17, "email": "dispatch@globaltradecorp.example", "phone": "+27 21 555 0142", "classification": "business" }, "destination_address": { "name": "Oliver Bennett", "company": "Bennett & Hale Ltd", "address_1": "221 Shoreditch High Street", "address_2": "Floor 2", "city": "London", "province": "Greater London", "postal_code": "E1 6PJ", "country_id": 18, "email": "goods-in@bennetthale.example", "phone": "+44 20 7946 0321", "classification": "business" } } }' ``` ## Example response (201) ```json { "order": { "id": 21, "assigned_admin": null, "battery_declaration_link": "", "broker_address": null, "ccd_status": "ccd_not_required", "commercial_invoice_link": "", "created_at": "2026/10/23 07:14:46 UTC", "customer_reference": "GTC-PO-20417", "customs_clearance_document_link": "", "date_delivered": null, "description_of_contents": "Cotton shirts and denim trousers", "destination_address": { "id": 98, "address_1": "221 Shoreditch High Street", "address_2": "Floor 2", "address_3": null, "city": "London", "classification": "business", "company": "Bennett & Hale Ltd", "country": { "id": 18, "default_postal_code": null, "dhl_export_code": null, "dhl_import_code": null, "dhl_tax_code": null, "export_code_label": "Export Number", "import_code_label": "Importer Code", "iso_code_2": "GB", "iso_code_3": "GBR", "name": "United Kingdom", "postal_code_required": true, "tax_number_label": "Tax Number", "vat_rate": 0.17 }, "country_id": 18, "email": "goods-in@bennetthale.example", "import_code": null, "latitude": null, "longitude": null, "name": "Oliver Bennett", "phone": "+442079460321", "postal_code": "E1 6PJ", "province": "Greater London", "summary": "United Kingdom", "tax_number": null, "time_zone_id": null }, "draft_bill_of_lading_link": "", "eei_eligible": false, "eei_request_document_link": "", "export_permit_link": "", "final_bill_of_lading_link": "", "importer_of_record_address": null, "internal_transaction_number": null, "invoice_data": { "billable_weights": { "metric": { "packages": 1, "mass_unit": "kg", "distance_unit": "cm", "volumetric_weight": 16.8, "weight": 12.5, "billable_weight": 16.8, "volume": 0.084 }, "imperial": { "packages": 1, "mass_unit": "lb", "distance_unit": "inches", "volumetric_weight": 37.04, "weight": 27.56, "billable_weight": 37.04, "volume": 2.9664316254643865 } }, "estimate_id": 16, "line_items": [ { "cost": 2184.5, "currency_id": "ZAR", "description": "Freight" }, { "cost": 393.21, "currency_id": "ZAR", "description": "Fuel surcharge" }, { "cost": 450, "currency_id": "ZAR", "description": "Customs clearance" } ], "quote_expired": false, "shipping_company": "FedEx South Africa", "shipping_service": "International Priority" }, "invoice_number": null, "materials_safety_data_sheet_link": "", "measured_weight": 0, "origin_address": { "id": 97, "address_1": "14 Bree Street", "address_2": "Unit 3", "address_3": null, "city": "Cape Town", "classification": "business", "company": "Global Trade Corp", "country": { "id": 17, "default_postal_code": null, "dhl_export_code": null, "dhl_import_code": null, "dhl_tax_code": null, "export_code_label": "Export Number", "import_code_label": "Importer Code", "iso_code_2": "ZA", "iso_code_3": "ZAF", "name": "South Africa", "postal_code_required": true, "tax_number_label": "Tax Number", "vat_rate": 0.17 }, "country_id": 17, "email": "dispatch@globaltradecorp.example", "import_code": null, "latitude": null, "longitude": null, "name": "Thandi Mokoena", "phone": "+27215550142", "postal_code": "8001", "province": "Western Cape", "summary": "South Africa", "tax_number": null, "time_zone_id": null }, "packaging_list_link": "", "pickup_date": null, "pickup_instructions": "", "proof_of_delivery_link": "", "purpose_of_shipment_id": 50, "quote_id": 21, "reference_number": "MYSGLO001000001", "scheduled_pickup": "", "send_consignee_tracking_details": false, "shipments": [ { "shipping_service": "International Priority", "status": "order_received", "tracking_link": null, "waybill": null, "waybill_document_link": "" } ], "shippers_letter_of_instruction_link": "", "status": "order_received", "stream_packing_list_link": "", "tracking_link": null, "value_of_goods": 18500, "value_of_goods_currency": "ZAR", "waybill": null, "waybill_document_link": "" } } ``` --- # Cancel an order `DELETE /client_api/v2/orders/{id}` Cancels an order that has not gone live yet. Otherwise the call answers 422. ## Parameters - `id` (integer, required): The order's id. Get it from List orders (`GET /client_api/v2/orders`): send the `id` of the one you want. Ids differ between the sandbox and production. ## Returns Returns the result. - `success` (boolean, required): Always `false` on an error. A successful delete answers `true`. - `error` (string, required): What went wrong, in one sentence. Empty on success. - `errors` (array of values, required): Each reason the request was refused, one per entry. Often empty, in which case `error` says it all. ## Errors - `401 Unauthorized`: The token is missing, expired or invalid. Sign in again. ## Example request (curl) ```bash curl -X DELETE "https://sandbox-api.vatit-stream.com/client_api/v2/orders/23" \ -H "Authorization: Bearer $API_TOKEN" ``` ## Example response (200) ```json { "success": true, "error": "", "errors": [] } ``` --- # Get an order `GET /client_api/v2/orders/{id}` ## Parameters - `id` (integer or string, required): The order's id. A reference number does not work here. Get it from List orders (`GET /client_api/v2/orders`): send the `id` of the one you want. Ids differ between the sandbox and production. ## Returns Returns the order. - `order` (object, required): The order. - `id` (integer, required): The order's id, for every call about the order. - `assigned_admin` (object, nullable, required): The email address of the person on our team looking after the order. Empty until one is assigned. - `battery_declaration_link` (string, required): A link to download the battery declaration. Empty until there is one. - `broker_address` (object, nullable, required): The customs broker clearing the goods, when one is appointed. Empty otherwise. - `ccd_status` (enum, required): Where we stand on the destination's customs clearance document (CCD), for orders where we get one. Possible enum values: `ccd_not_required`, `ccd_required`, `voucher_of_correction_requested`, `voucher_of_correction_received`, `ccd_acquired`. - `commercial_invoice_link` (string, required): A link to download the commercial invoice. Empty until there is one. - `created_at` (string, required): When the order was placed, as `YYYY/MM/DD HH:MM:SS UTC`. - `customer_reference` (string, nullable, required): Your own reference for the order. - `customs_clearance_document_link` (string, required): A link to download the customs clearance document. Empty until there is one. - `date_delivered` (object, nullable, required): When the goods were delivered, as `YYYY/MM/DD HH:MM:SS UTC`. Empty until then. - `description_of_contents` (string, nullable, required): What is in the shipment. - `destination_address` (object, required): Where the goods are delivered. - `id` (integer, required): The address's id. Send it as `origin_address_id` or `destination_address_id` to use the address again. - `address_1` (string, required): The street address. At most 34 characters. - `address_2` (string, required): A second address line, such as a floor or unit. At most 34 characters. - `address_3` (string, nullable, required): A third address line. - `city` (string, required): The city or town. At most 20 characters. - `classification` (enum, required): Whether the address is a business or a home. Carriers charge more to deliver to a home. Possible enum values: `business`, `residential`. - `company` (string, required): The company at the address. At most 35 characters. - `country` (object, required): The country, in full. - `id` (integer, required): The country's id, for an address's `country_id`. - `default_postal_code` (object, nullable, required): The postal code we give the carrier for an address in this country that has none. - `dhl_export_code` (object, nullable, required): DHL's export code for the country. Usually empty. - `dhl_import_code` (object, nullable, required): DHL's import code for the country. Usually empty. - `dhl_tax_code` (object, nullable, required): DHL's tax code for the country. Usually empty. - `export_code_label` (string, required): What the country calls an exporter number. - `import_code_label` (string, required): What the country calls an importer number. - `iso_code_2` (string, required): The two-letter ISO code, such as `GB`. - `iso_code_3` (string, required): The three-letter ISO code, such as `GBR`. - `name` (string, required): The country's name in English. - `postal_code_required` (boolean, required): `false` for the countries that have no postal codes. - `tax_number_label` (string, required): What the country calls a tax number. - `vat_rate` (number, required): The country's standard VAT or sales tax rate, as a fraction. `0.15` is 15%. - `country_id` (integer, required): The country. Take the id from List countries. - `email` (string, required): An email address for the person at the address. Carriers use it for delivery notices. - `import_code` (string, nullable, required): The importer number of the party at the address. The country's `import_code_label` says what it is called there. - `latitude` (object, nullable, required): Where the address is, filled in by us shortly after the address is saved. Empty until then. - `longitude` (object, nullable, required): Where the address is, filled in by us shortly after the address is saved. Empty until then. - `name` (string, required): The person to ask for. At most 35 characters. - `phone` (string, required): A phone number for the person at the address. At most 15 characters. - `postal_code` (string, required): The postal code. Some countries, such as Ireland, refuse an address without one. - `province` (string, required): The province, state or county. - `summary` (string, required): The country's name. - `tax_number` (object, nullable, required): The tax or VAT number of the party at the address. The country's `tax_number_label` says what it is called there. - `time_zone_id` (object, nullable, required): The address's time zone, filled in by us shortly after the address is saved. Empty until then. - `draft_bill_of_lading_link` (string, required): A link to download the draft bill of lading. Empty until there is one. - `eei_eligible` (boolean, required): `true` when the shipment needs an Electronic Export Information filing with US customs. - `eei_request_document_link` (string, required): A link to download the export filing request. Empty until there is one. - `export_permit_link` (string, required): A link to download the export permit. Empty until there is one. - `final_bill_of_lading_link` (string, required): A link to download the final bill of lading. Empty until there is one. - `importer_of_record_address` (object, nullable, required): The importer of record, when the shipment has one. Empty otherwise. - `internal_transaction_number` (object, nullable, required): The US customs reference (ITN) for the export filing. Empty unless one was filed. - `invoice_data` (object, required): The booked estimate, with its weights and charges. Empty until an estimate is booked. - `billable_weights` (object, required): The weights the carrier charges on, in metric and in imperial units. - `metric` (object, required): The weights in kilograms, the sizes in centimetres and the volume in cubic metres. - `packages` (integer, required): How many packages there are. - `mass_unit` (string, required): Always `kg`. - `distance_unit` (string, required): Always `cm`. - `volumetric_weight` (number, required): The weight the carrier works out from the packages' size. - `weight` (number, required): What the packages weigh together. - `billable_weight` (number, required): The weight the carrier charges on, the larger of `weight` and `volumetric_weight`. - `volume` (number, required): The packages' volume together. - `imperial` (object, required): The weights in pounds, the sizes in inches and the volume in cubic feet. - `packages` (integer, required): How many packages there are. - `mass_unit` (string, required): Always `lb`. - `distance_unit` (string, required): Always `inches`. A request spells the same unit `inch`. - `volumetric_weight` (number, required): The weight the carrier works out from the packages' size. - `weight` (number, required): What the packages weigh together. - `billable_weight` (number, required): The weight the carrier charges on, the larger of `weight` and `volumetric_weight`. - `volume` (number, required): The packages' volume together. - `estimate_id` (integer, required): The estimate's id. Book it by sending it as an order's `quote_estimate_id`. - `line_items` (array of objects, required): What the price is made of, one charge per line. - `cost` (number, required): What the charge costs, in `currency_id`. - `currency_id` (string, required): The currency the company is billed in. - `description` (string, required): The charge, such as freight or fuel surcharge. - `quote_expired` (boolean, required): `true` when this price no longer holds, because another estimate was booked or the shipment changed. Get a new quote. - `shipping_company` (string, required): The carrier. - `shipping_service` (string, required): The carrier's service, such as International Priority. - `invoice_number` (object, nullable, required): Our invoice number for the order. Empty until we invoice it. - `materials_safety_data_sheet_link` (string, required): A link to download the materials safety data sheet. Empty until there is one. - `measured_weight` (number, required): What the carrier weighed the shipment at, in kilograms. `0` until the carrier weighs it. - `origin_address` (object, required): Where the carrier collects the goods. - `id` (integer, required): The address's id. Send it as `origin_address_id` or `destination_address_id` to use the address again. - `address_1` (string, required): The street address. At most 34 characters. - `address_2` (string, required): A second address line, such as a floor or unit. At most 34 characters. - `address_3` (string, nullable, required): A third address line. - `city` (string, required): The city or town. At most 20 characters. - `classification` (enum, required): Whether the address is a business or a home. Carriers charge more to deliver to a home. Possible enum values: `business`, `residential`. - `company` (string, required): The company at the address. At most 35 characters. - `country` (object, required): The country, in full. - `id` (integer, required): The country's id, for an address's `country_id`. - `default_postal_code` (object, nullable, required): The postal code we give the carrier for an address in this country that has none. - `dhl_export_code` (object, nullable, required): DHL's export code for the country. Usually empty. - `dhl_import_code` (object, nullable, required): DHL's import code for the country. Usually empty. - `dhl_tax_code` (object, nullable, required): DHL's tax code for the country. Usually empty. - `export_code_label` (string, required): What the country calls an exporter number. - `import_code_label` (string, required): What the country calls an importer number. - `iso_code_2` (string, required): The two-letter ISO code, such as `GB`. - `iso_code_3` (string, required): The three-letter ISO code, such as `GBR`. - `name` (string, required): The country's name in English. - `postal_code_required` (boolean, required): `false` for the countries that have no postal codes. - `tax_number_label` (string, required): What the country calls a tax number. - `vat_rate` (number, required): The country's standard VAT or sales tax rate, as a fraction. `0.15` is 15%. - `country_id` (integer, required): The country. Take the id from List countries. - `email` (string, required): An email address for the person at the address. Carriers use it for delivery notices. - `import_code` (string, nullable, required): The importer number of the party at the address. The country's `import_code_label` says what it is called there. - `latitude` (object, nullable, required): Where the address is, filled in by us shortly after the address is saved. Empty until then. - `longitude` (object, nullable, required): Where the address is, filled in by us shortly after the address is saved. Empty until then. - `name` (string, required): The person to ask for. At most 35 characters. - `phone` (string, required): A phone number for the person at the address. At most 15 characters. - `postal_code` (string, required): The postal code. Some countries, such as Ireland, refuse an address without one. - `province` (string, required): The province, state or county. - `summary` (string, required): The country's name. - `tax_number` (object, nullable, required): The tax or VAT number of the party at the address. The country's `tax_number_label` says what it is called there. - `time_zone_id` (object, nullable, required): The address's time zone, filled in by us shortly after the address is saved. Empty until then. - `packaging_list_link` (string, required): A link to download the packing list you uploaded. Empty until there is one. - `pickup_date` (string, nullable, required): The day the carrier collected the goods, as `YYYY-MM-DD`. Empty until then. - `pickup_instructions` (string, required): What the driver was told when the pickup was booked. Empty when none is booked. - `proof_of_delivery_link` (string, required): A link to download the proof of delivery. Empty until there is one. - `purpose_of_shipment_id` (integer, required): The incoterm the goods move under. - `quote_id` (integer, required): The quote the order was booked from. - `reference_number` (string, required): Our reference for the order, the one our team and the client portal use, for example `MYSGLO001000001`. - `scheduled_pickup` (string, required): The pickup booked for the order. An empty string, not an empty object, when none is booked. - `send_consignee_tracking_details` (boolean, required): `true` when the receiver is sent the tracking details. - `shipments` (array of objects, required): Each leg of the shipment, in route order. Most orders have one. - `shipping_service` (string, required): The carrier's service for this leg. - `status` (enum, required): Where this leg is. List order statuses has every value. Possible enum values: `incomplete`, `order_received`, `awaiting_additional_documentation`, `awaiting_prepayment`, `awaiting_waybill_generation`, `awaiting_schedule_pickup`, `awaiting_pickup`, `awaiting_swap_out`, `pickup_missed`, `in_transit`, `partially_delivered`, `delivered`, `invoice_to_be_paid`, `invoice_paid`, `cancelled`, `lost_in_transit`, `awaiting_consolidation`, `consolidated`. - `tracking_link` (object, nullable, required): The carrier's tracking page for this leg. Empty until there is a waybill. - `waybill` (string, nullable, required): The carrier's waybill number for this leg. Empty until there is one. - `waybill_document_link` (string, required): A link to download this leg's waybill. Empty until there is one. - `shippers_letter_of_instruction_link` (string, required): A link to download the shipper's letter of instruction. Empty until there is one. - `status` (enum, required): Where the shipment is. For an order with more than one leg, the last leg's status. List order statuses has every value. Possible enum values: `incomplete`, `order_received`, `awaiting_additional_documentation`, `awaiting_prepayment`, `awaiting_waybill_generation`, `awaiting_schedule_pickup`, `awaiting_pickup`, `awaiting_swap_out`, `pickup_missed`, `in_transit`, `partially_delivered`, `delivered`, `invoice_to_be_paid`, `invoice_paid`, `cancelled`, `lost_in_transit`, `awaiting_consolidation`, `consolidated`. - `stream_packing_list_link` (string, required): A link to download the packing list we made. Empty until there is one. - `tracking_link` (object, nullable, required): The carrier's tracking page for the shipment. Empty until there is a waybill. - `value_of_goods` (number, required): What the goods are worth in total. - `value_of_goods_currency` (string, required): The currency of `value_of_goods`, as a three-letter code. - `waybill` (string, nullable, required): The carrier's waybill number. Empty until Create a waybill has run. - `waybill_document_link` (string, required): A link to download the waybill. Empty until there is one. ## Errors - `400 Bad Request`: The request body isn't valid JSON, or something failed on our side. - `401 Unauthorized`: The token is missing, expired or invalid. Sign in again. - `404 Not Found`: The record doesn't exist, or belongs to another company. ## Example request (curl) ```bash curl -X GET "https://sandbox-api.vatit-stream.com/client_api/v2/orders/0" \ -H "Authorization: Bearer $API_TOKEN" ``` ## Example response (200) ```json { "order": { "id": 24, "assigned_admin": null, "battery_declaration_link": "", "broker_address": null, "ccd_status": "ccd_not_required", "commercial_invoice_link": "", "created_at": "2026/10/23 07:14:46 UTC", "customer_reference": "GTC-PO-20417", "customs_clearance_document_link": "", "date_delivered": null, "description_of_contents": "Cotton shirts and denim trousers", "destination_address": { "id": 116, "address_1": "221 Shoreditch High Street", "address_2": "Floor 2", "address_3": null, "city": "London", "classification": "business", "company": "Bennett & Hale Ltd", "country": { "id": 18, "default_postal_code": null, "dhl_export_code": null, "dhl_import_code": null, "dhl_tax_code": null, "export_code_label": "Export Number", "import_code_label": "Importer Code", "iso_code_2": "GB", "iso_code_3": "GBR", "name": "United Kingdom", "postal_code_required": true, "tax_number_label": "Tax Number", "vat_rate": 0.17 }, "country_id": 18, "email": "goods-in@bennetthale.example", "import_code": null, "latitude": null, "longitude": null, "name": "Oliver Bennett", "phone": "+442079460321", "postal_code": "E1 6PJ", "province": "Greater London", "summary": "United Kingdom", "tax_number": null, "time_zone_id": null }, "draft_bill_of_lading_link": "", "eei_eligible": false, "eei_request_document_link": "", "export_permit_link": "", "final_bill_of_lading_link": "", "importer_of_record_address": null, "internal_transaction_number": null, "invoice_data": { "billable_weights": { "metric": { "packages": 1, "mass_unit": "kg", "distance_unit": "cm", "volumetric_weight": 16.8, "weight": 12.5, "billable_weight": 16.8, "volume": 0.084 }, "imperial": { "packages": 1, "mass_unit": "lb", "distance_unit": "inches", "volumetric_weight": 37.04, "weight": 27.56, "billable_weight": 37.04, "volume": 2.9664316254643865 } }, "estimate_id": 19, "line_items": [ { "cost": 2184.5, "currency_id": "ZAR", "description": "Freight" }, { "cost": 393.21, "currency_id": "ZAR", "description": "Fuel surcharge" }, { "cost": 450, "currency_id": "ZAR", "description": "Customs clearance" } ], "quote_expired": false, "shipping_company": "FedEx South Africa", "shipping_service": "International Priority" }, "invoice_number": null, "materials_safety_data_sheet_link": "", "measured_weight": 0, "origin_address": { "id": 115, "address_1": "14 Bree Street", "address_2": "Unit 3", "address_3": null, "city": "Cape Town", "classification": "business", "company": "Global Trade Corp", "country": { "id": 17, "default_postal_code": null, "dhl_export_code": null, "dhl_import_code": null, "dhl_tax_code": null, "export_code_label": "Export Number", "import_code_label": "Importer Code", "iso_code_2": "ZA", "iso_code_3": "ZAF", "name": "South Africa", "postal_code_required": true, "tax_number_label": "Tax Number", "vat_rate": 0.17 }, "country_id": 17, "email": "dispatch@globaltradecorp.example", "import_code": null, "latitude": null, "longitude": null, "name": "Thandi Mokoena", "phone": "+27215550142", "postal_code": "8001", "province": "Western Cape", "summary": "South Africa", "tax_number": null, "time_zone_id": null }, "packaging_list_link": "", "pickup_date": null, "pickup_instructions": "", "proof_of_delivery_link": "", "purpose_of_shipment_id": 50, "quote_id": 24, "reference_number": "MYSGLO001000001", "scheduled_pickup": "", "send_consignee_tracking_details": false, "shipments": [ { "shipping_service": "International Priority", "status": "order_received", "tracking_link": null, "waybill": null, "waybill_document_link": "" } ], "shippers_letter_of_instruction_link": "", "status": "order_received", "stream_packing_list_link": "", "tracking_link": null, "value_of_goods": 18500, "value_of_goods_currency": "ZAR", "waybill": null, "waybill_document_link": "" } } ``` --- # List pickup slots `GET /client_api/v2/orders/{order_id}/pickup_availabilities` The days and times the carrier can collect the order. Pick a slot from here before you book a pickup. ## Parameters - `order_id` (integer, required): The order's id. Get it from List orders (`GET /client_api/v2/orders`): send the `id` of the one you want. Ids differ between the sandbox and production. ## Returns Returns a list. - `earliest_pickup_time` (string, required): The earliest the goods can be ready, as `HH:MM`. - `latest_pickup_end_time` (string, required): The latest the collection point can close, as `HH:MM`. - `latest_pickup_start_time` (string, required): The latest the goods can be ready, as `HH:MM`. - `minimum_access_duration_minutes` (integer, required): How long, at least, the driver needs between ready time and closing time. - `pickup_date` (string, required): A day the carrier can collect, as `YYYY-MM-DD`. - `time_zone_id` (object, nullable, required): The time zone the times are in. Usually empty, in which case they are local to the collection address. ## Errors - `401 Unauthorized`: The token is missing, expired or invalid. Sign in again. ## Example request (curl) ```bash curl -X GET "https://sandbox-api.vatit-stream.com/client_api/v2/orders/1/pickup_availabilities" \ -H "Authorization: Bearer $API_TOKEN" ``` ## Example response (200) ```json [ { "earliest_pickup_time": "09:00", "latest_pickup_end_time": "16:30", "latest_pickup_start_time": "15:00", "minimum_access_duration_minutes": 90, "pickup_date": "2026-10-26", "time_zone_id": null } ] ``` --- # List pickups `GET /client_api/v2/orders/{order_id}/schedule_pickups` Every pickup booked for the order, newest first, including cancelled ones. ## Parameters - `order_id` (integer, required): The order's id. Get it from List orders (`GET /client_api/v2/orders`): send the `id` of the one you want. Ids differ between the sandbox and production. ## Returns Returns the result. - `scheduled_pickups` (array of objects, required): The order's pickups, newest first. - `id` (integer, required): The pickup's id. - `cancellable` (boolean, required): `true` while the booking can still be cancelled with the carrier. - `confirmation_number` (string, required): The carrier's confirmation number for the booking. - `error_message` (string, required): `Invalid postal code` when the carrier refused the booking over the postal code. Empty for every other outcome, including other refusals. - `freight_confirmation_number` (object, nullable, required): The carrier's second confirmation number, for freight collected separately. Usually empty. - `order_status` (enum, required): Where the order is. List order statuses has every value. Possible enum values: `incomplete`, `order_received`, `awaiting_additional_documentation`, `awaiting_prepayment`, `awaiting_waybill_generation`, `awaiting_schedule_pickup`, `awaiting_pickup`, `awaiting_swap_out`, `pickup_missed`, `in_transit`, `partially_delivered`, `delivered`, `invoice_to_be_paid`, `invoice_paid`, `cancelled`, `lost_in_transit`, `awaiting_consolidation`, `consolidated`. - `scheduled_date` (string, required): The collection day, as `YYYY/MM/DD HH:MM:SS UTC`. The time is always midnight, so read only the date. - `status` (enum, required): Where the booking stands. `system_to_schedule` means we are still booking it with the carrier. Possible enum values: `scheduled`, `cancelled`, `errored`, `system_to_schedule`, `missed`. - `time_from` (string, required): When the goods are ready, as `HH:MM:SS`. - `time_to` (string, required): When the collection point closes, as `HH:MM:SS`. - `meta` (object, required): How many pages and records the list has. - `page_count` (integer, required): How many pages the list has. Ask for another with `?page=`. - `record_count` (integer, required): How many records the list has across all pages. ## Errors - `401 Unauthorized`: The token is missing, expired or invalid. Sign in again. ## Example request (curl) ```bash curl -X GET "https://sandbox-api.vatit-stream.com/client_api/v2/orders/5/schedule_pickups" \ -H "Authorization: Bearer $API_TOKEN" ``` ## Example response (200) ```json { "scheduled_pickups": [ { "id": 2, "cancellable": true, "confirmation_number": "FDX-PU-4417823", "error_message": "", "freight_confirmation_number": null, "order_status": "awaiting_pickup", "scheduled_date": "2026/10/26 00:00:00 UTC", "status": "scheduled", "time_from": "10:00:00", "time_to": "16:00:00" } ], "meta": { "page_count": 1, "record_count": 1 } } ``` --- # Book a pickup `POST /client_api/v2/orders/{order_id}/schedule_pickups` Books the carrier to collect the order, inside one of the slots from List pickup slots. Booking again cancels the earlier pickup. ## Parameters - `order_id` (integer, required): The order's id. Get it from List orders (`GET /client_api/v2/orders`): send the `id` of the one you want. Ids differ between the sandbox and production. ## Body - `scheduled_pickup` (object, required): The pickup to book. - `scheduled_date` (string, required): The day to collect, as `YYYY-MM-DD`. It has to be a day from List pickup slots. - `time_from` (string, required): When the goods are ready, as `HH:MM` in the collection address's local time. No earlier than the slot's `earliest_pickup_time` and no later than its `latest_pickup_start_time`. - `time_to` (string, required): When the collection point closes, as `HH:MM`. No later than the slot's `latest_pickup_end_time`, and at least `minimum_access_duration_minutes` after `time_from`. - `pickup_instructions` (string): Anything the driver needs to know, such as which door to use. ## Returns Returns the scheduled pickup. - `scheduled_pickup` (object, required): The pickup. - `id` (integer, required): The pickup's id. - `cancellable` (boolean, required): `true` while the booking can still be cancelled with the carrier. - `confirmation_number` (string, required): The carrier's confirmation number for the booking. - `error_message` (string, required): `Invalid postal code` when the carrier refused the booking over the postal code. Empty for every other outcome, including other refusals. - `freight_confirmation_number` (object, nullable, required): The carrier's second confirmation number, for freight collected separately. Usually empty. - `pickup_instructions` (string, required): What the driver was told. - `scheduled_date` (string, required): The collection day, as `YYYY/MM/DD HH:MM:SS UTC`. The time is always midnight, so read only the date. - `status` (enum, required): Where the booking stands. `system_to_schedule` means we are still booking it with the carrier. Possible enum values: `scheduled`, `cancelled`, `errored`, `system_to_schedule`, `missed`. - `time_from` (string, required): When the goods are ready, as `HH:MM:SS`. - `time_to` (string, required): When the collection point closes, as `HH:MM:SS`. ## Errors - `400 Bad Request`: The request body isn't valid JSON, or something failed on our side. - `401 Unauthorized`: The token is missing, expired or invalid. Sign in again. ## Example request (curl) ```bash curl -X POST "https://sandbox-api.vatit-stream.com/client_api/v2/orders/4/schedule_pickups" \ -H "Authorization: Bearer $API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "scheduled_pickup": { "scheduled_date": "2026-10-26", "time_from": "10:00", "time_to": "16:00", "pickup_instructions": "Collect from reception and ask for Thandi" } }' ``` ## Example response (201) ```json { "scheduled_pickup": { "id": 1, "cancellable": true, "confirmation_number": "FDX-PU-4417823", "error_message": "", "freight_confirmation_number": null, "pickup_instructions": "Collect from reception and ask for Thandi", "scheduled_date": "2026/10/26 00:00:00 UTC", "status": "scheduled", "time_from": "10:00:00", "time_to": "16:00:00" } } ``` --- # List tracking events `GET /client_api/v2/orders/{order_id}/tracking` What the carrier has reported about the shipment, newest first. ## Parameters - `order_id` (integer, required): The order's id. Get it from List orders (`GET /client_api/v2/orders`): send the `id` of the one you want. Ids differ between the sandbox and production. ## Returns Returns the result. - `shipment_events` (array of objects, required): The tracking events on this page, newest first. - `id` (integer, required): The event's id. - `date_time` (string, required): When it happened, as `YYYY/MM/DD HH:MM:SS UTC`. - `description` (string, required): What happened, in the carrier's words. - `latitude` (object, nullable, required): Where it happened, when the carrier says. Usually empty. - `location` (string, required): Where it happened, as the carrier reports it. - `longitude` (object, nullable, required): Where it happened, when the carrier says. Usually empty. - `order_id` (integer, required): The order the event belongs to. - `meta` (object, required): How many pages and records the list has. - `page_count` (integer, required): How many pages the list has. Ask for another with `?page=`. - `record_count` (integer, required): How many records the list has across all pages. ## Errors - `401 Unauthorized`: The token is missing, expired or invalid. Sign in again. ## Example request (curl) ```bash curl -X GET "https://sandbox-api.vatit-stream.com/client_api/v2/orders/3/tracking" \ -H "Authorization: Bearer $API_TOKEN" ``` ## Example response (200) ```json { "shipment_events": [ { "id": 3, "date_time": "2026/10/28 09:12:00 UTC", "description": "Arrived at FedEx hub", "latitude": null, "location": "STANSTED, GB", "longitude": null, "order_id": 3 }, { "id": 2, "date_time": "2026/10/27 03:40:00 UTC", "description": "Departed FedEx hub", "latitude": null, "location": "JOHANNESBURG, ZA", "longitude": null, "order_id": 3 }, { "id": 1, "date_time": "2026/10/26 14:05:00 UTC", "description": "Picked up", "latitude": null, "location": "CAPE TOWN, ZA", "longitude": null, "order_id": 3 } ], "meta": { "page_count": 1, "record_count": 3 } } ``` --- # Create a waybill `POST /client_api/v2/orders/{order_id}/waybills` Asks the carrier for the order's waybill and answers with the order, now holding the waybill number and a link to its document. If the carrier refuses, or a document or payment is missing, the call answers 422 with the reason. Don't retry this call after a timeout: the first request may still be booking with the carrier, and a retry books a second waybill. Read the order with Get an order first, and call this again only if it has no waybill. ## Parameters - `order_id` (integer, required): The order's id. Get it from List orders (`GET /client_api/v2/orders`): send the `id` of the one you want. Ids differ between the sandbox and production. ## Returns Returns the order. - `order` (object, required): The order. - `id` (integer, required): The order's id, for every call about the order. - `assigned_admin` (object, nullable, required): The email address of the person on our team looking after the order. Empty until one is assigned. - `battery_declaration_link` (string, required): A link to download the battery declaration. Empty until there is one. - `broker_address` (object, nullable, required): The customs broker clearing the goods, when one is appointed. Empty otherwise. - `ccd_status` (enum, required): Where we stand on the destination's customs clearance document (CCD), for orders where we get one. Possible enum values: `ccd_not_required`, `ccd_required`, `voucher_of_correction_requested`, `voucher_of_correction_received`, `ccd_acquired`. - `commercial_invoice_link` (string, required): A link to download the commercial invoice. Empty until there is one. - `created_at` (string, required): When the order was placed, as `YYYY/MM/DD HH:MM:SS UTC`. - `customer_reference` (string, nullable, required): Your own reference for the order. - `customs_clearance_document_link` (string, required): A link to download the customs clearance document. Empty until there is one. - `date_delivered` (object, nullable, required): When the goods were delivered, as `YYYY/MM/DD HH:MM:SS UTC`. Empty until then. - `description_of_contents` (string, nullable, required): What is in the shipment. - `destination_address` (object, required): Where the goods are delivered. - `id` (integer, required): The address's id. Send it as `origin_address_id` or `destination_address_id` to use the address again. - `address_1` (string, required): The street address. At most 34 characters. - `address_2` (string, required): A second address line, such as a floor or unit. At most 34 characters. - `address_3` (string, nullable, required): A third address line. - `city` (string, required): The city or town. At most 20 characters. - `classification` (enum, required): Whether the address is a business or a home. Carriers charge more to deliver to a home. Possible enum values: `business`, `residential`. - `company` (string, required): The company at the address. At most 35 characters. - `country` (object, required): The country, in full. - `id` (integer, required): The country's id, for an address's `country_id`. - `default_postal_code` (object, nullable, required): The postal code we give the carrier for an address in this country that has none. - `dhl_export_code` (object, nullable, required): DHL's export code for the country. Usually empty. - `dhl_import_code` (object, nullable, required): DHL's import code for the country. Usually empty. - `dhl_tax_code` (object, nullable, required): DHL's tax code for the country. Usually empty. - `export_code_label` (string, required): What the country calls an exporter number. - `import_code_label` (string, required): What the country calls an importer number. - `iso_code_2` (string, required): The two-letter ISO code, such as `GB`. - `iso_code_3` (string, required): The three-letter ISO code, such as `GBR`. - `name` (string, required): The country's name in English. - `postal_code_required` (boolean, required): `false` for the countries that have no postal codes. - `tax_number_label` (string, required): What the country calls a tax number. - `vat_rate` (number, required): The country's standard VAT or sales tax rate, as a fraction. `0.15` is 15%. - `country_id` (integer, required): The country. Take the id from List countries. - `email` (string, required): An email address for the person at the address. Carriers use it for delivery notices. - `import_code` (string, nullable, required): The importer number of the party at the address. The country's `import_code_label` says what it is called there. - `latitude` (object, nullable, required): Where the address is, filled in by us shortly after the address is saved. Empty until then. - `longitude` (object, nullable, required): Where the address is, filled in by us shortly after the address is saved. Empty until then. - `name` (string, required): The person to ask for. At most 35 characters. - `phone` (string, required): A phone number for the person at the address. At most 15 characters. - `postal_code` (string, required): The postal code. Some countries, such as Ireland, refuse an address without one. - `province` (string, required): The province, state or county. - `summary` (string, required): The country's name. - `tax_number` (object, nullable, required): The tax or VAT number of the party at the address. The country's `tax_number_label` says what it is called there. - `time_zone_id` (object, nullable, required): The address's time zone, filled in by us shortly after the address is saved. Empty until then. - `draft_bill_of_lading_link` (string, required): A link to download the draft bill of lading. Empty until there is one. - `eei_eligible` (boolean, required): `true` when the shipment needs an Electronic Export Information filing with US customs. - `eei_request_document_link` (string, required): A link to download the export filing request. Empty until there is one. - `export_permit_link` (string, required): A link to download the export permit. Empty until there is one. - `final_bill_of_lading_link` (string, required): A link to download the final bill of lading. Empty until there is one. - `importer_of_record_address` (object, nullable, required): The importer of record, when the shipment has one. Empty otherwise. - `internal_transaction_number` (object, nullable, required): The US customs reference (ITN) for the export filing. Empty unless one was filed. - `invoice_data` (object, required): The booked estimate, with its weights and charges. Empty until an estimate is booked. - `billable_weights` (object, required): The weights the carrier charges on, in metric and in imperial units. - `metric` (object, required): The weights in kilograms, the sizes in centimetres and the volume in cubic metres. - `packages` (integer, required): How many packages there are. - `mass_unit` (string, required): Always `kg`. - `distance_unit` (string, required): Always `cm`. - `volumetric_weight` (number, required): The weight the carrier works out from the packages' size. - `weight` (number, required): What the packages weigh together. - `billable_weight` (number, required): The weight the carrier charges on, the larger of `weight` and `volumetric_weight`. - `volume` (number, required): The packages' volume together. - `imperial` (object, required): The weights in pounds, the sizes in inches and the volume in cubic feet. - `packages` (integer, required): How many packages there are. - `mass_unit` (string, required): Always `lb`. - `distance_unit` (string, required): Always `inches`. A request spells the same unit `inch`. - `volumetric_weight` (number, required): The weight the carrier works out from the packages' size. - `weight` (number, required): What the packages weigh together. - `billable_weight` (number, required): The weight the carrier charges on, the larger of `weight` and `volumetric_weight`. - `volume` (number, required): The packages' volume together. - `estimate_id` (integer, required): The estimate's id. Book it by sending it as an order's `quote_estimate_id`. - `line_items` (array of objects, required): What the price is made of, one charge per line. - `cost` (number, required): What the charge costs, in `currency_id`. - `currency_id` (string, required): The currency the company is billed in. - `description` (string, required): The charge, such as freight or fuel surcharge. - `quote_expired` (boolean, required): `true` when this price no longer holds, because another estimate was booked or the shipment changed. Get a new quote. - `shipping_company` (string, required): The carrier. - `shipping_service` (string, required): The carrier's service, such as International Priority. - `invoice_number` (object, nullable, required): Our invoice number for the order. Empty until we invoice it. - `materials_safety_data_sheet_link` (string, required): A link to download the materials safety data sheet. Empty until there is one. - `measured_weight` (number, required): What the carrier weighed the shipment at, in kilograms. `0` until the carrier weighs it. - `origin_address` (object, required): Where the carrier collects the goods. - `id` (integer, required): The address's id. Send it as `origin_address_id` or `destination_address_id` to use the address again. - `address_1` (string, required): The street address. At most 34 characters. - `address_2` (string, required): A second address line, such as a floor or unit. At most 34 characters. - `address_3` (string, nullable, required): A third address line. - `city` (string, required): The city or town. At most 20 characters. - `classification` (enum, required): Whether the address is a business or a home. Carriers charge more to deliver to a home. Possible enum values: `business`, `residential`. - `company` (string, required): The company at the address. At most 35 characters. - `country` (object, required): The country, in full. - `id` (integer, required): The country's id, for an address's `country_id`. - `default_postal_code` (object, nullable, required): The postal code we give the carrier for an address in this country that has none. - `dhl_export_code` (object, nullable, required): DHL's export code for the country. Usually empty. - `dhl_import_code` (object, nullable, required): DHL's import code for the country. Usually empty. - `dhl_tax_code` (object, nullable, required): DHL's tax code for the country. Usually empty. - `export_code_label` (string, required): What the country calls an exporter number. - `import_code_label` (string, required): What the country calls an importer number. - `iso_code_2` (string, required): The two-letter ISO code, such as `GB`. - `iso_code_3` (string, required): The three-letter ISO code, such as `GBR`. - `name` (string, required): The country's name in English. - `postal_code_required` (boolean, required): `false` for the countries that have no postal codes. - `tax_number_label` (string, required): What the country calls a tax number. - `vat_rate` (number, required): The country's standard VAT or sales tax rate, as a fraction. `0.15` is 15%. - `country_id` (integer, required): The country. Take the id from List countries. - `email` (string, required): An email address for the person at the address. Carriers use it for delivery notices. - `import_code` (string, nullable, required): The importer number of the party at the address. The country's `import_code_label` says what it is called there. - `latitude` (object, nullable, required): Where the address is, filled in by us shortly after the address is saved. Empty until then. - `longitude` (object, nullable, required): Where the address is, filled in by us shortly after the address is saved. Empty until then. - `name` (string, required): The person to ask for. At most 35 characters. - `phone` (string, required): A phone number for the person at the address. At most 15 characters. - `postal_code` (string, required): The postal code. Some countries, such as Ireland, refuse an address without one. - `province` (string, required): The province, state or county. - `summary` (string, required): The country's name. - `tax_number` (object, nullable, required): The tax or VAT number of the party at the address. The country's `tax_number_label` says what it is called there. - `time_zone_id` (object, nullable, required): The address's time zone, filled in by us shortly after the address is saved. Empty until then. - `packaging_list_link` (string, required): A link to download the packing list you uploaded. Empty until there is one. - `pickup_date` (string, nullable, required): The day the carrier collected the goods, as `YYYY-MM-DD`. Empty until then. - `pickup_instructions` (string, required): What the driver was told when the pickup was booked. Empty when none is booked. - `proof_of_delivery_link` (string, required): A link to download the proof of delivery. Empty until there is one. - `purpose_of_shipment_id` (integer, required): The incoterm the goods move under. - `quote_id` (integer, required): The quote the order was booked from. - `reference_number` (string, required): Our reference for the order, the one our team and the client portal use, for example `MYSGLO001000001`. - `scheduled_pickup` (string, required): The pickup booked for the order. An empty string, not an empty object, when none is booked. - `send_consignee_tracking_details` (boolean, required): `true` when the receiver is sent the tracking details. - `shipments` (array of objects, required): Each leg of the shipment, in route order. Most orders have one. - `shipping_service` (string, required): The carrier's service for this leg. - `status` (enum, required): Where this leg is. List order statuses has every value. Possible enum values: `incomplete`, `order_received`, `awaiting_additional_documentation`, `awaiting_prepayment`, `awaiting_waybill_generation`, `awaiting_schedule_pickup`, `awaiting_pickup`, `awaiting_swap_out`, `pickup_missed`, `in_transit`, `partially_delivered`, `delivered`, `invoice_to_be_paid`, `invoice_paid`, `cancelled`, `lost_in_transit`, `awaiting_consolidation`, `consolidated`. - `tracking_link` (string, nullable, required): The carrier's tracking page for this leg. Empty until there is a waybill. - `waybill` (string, nullable, required): The carrier's waybill number for this leg. Empty until there is one. - `waybill_document_link` (string, required): A link to download this leg's waybill. Empty until there is one. - `shippers_letter_of_instruction_link` (string, required): A link to download the shipper's letter of instruction. Empty until there is one. - `status` (enum, required): Where the shipment is. For an order with more than one leg, the last leg's status. List order statuses has every value. Possible enum values: `incomplete`, `order_received`, `awaiting_additional_documentation`, `awaiting_prepayment`, `awaiting_waybill_generation`, `awaiting_schedule_pickup`, `awaiting_pickup`, `awaiting_swap_out`, `pickup_missed`, `in_transit`, `partially_delivered`, `delivered`, `invoice_to_be_paid`, `invoice_paid`, `cancelled`, `lost_in_transit`, `awaiting_consolidation`, `consolidated`. - `stream_packing_list_link` (string, required): A link to download the packing list we made. Empty until there is one. - `tracking_link` (string, nullable, required): The carrier's tracking page for the shipment. Empty until there is a waybill. - `value_of_goods` (number, required): What the goods are worth in total. - `value_of_goods_currency` (string, required): The currency of `value_of_goods`, as a three-letter code. - `waybill` (string, nullable, required): The carrier's waybill number. Empty until Create a waybill has run. - `waybill_document_link` (string, required): A link to download the waybill. Empty until there is one. ## Errors - `400 Bad Request`: The request body isn't valid JSON, or something failed on our side. - `401 Unauthorized`: The token is missing, expired or invalid. Sign in again. - `403 Forbidden`: Your login isn't allowed to do this. - `422 Unprocessable Content`: The request was refused. `error` says why in one sentence, and `errors` lists each reason. ## Example request (curl) ```bash curl -X POST "https://sandbox-api.vatit-stream.com/client_api/v2/orders/11/waybills" \ -H "Authorization: Bearer $API_TOKEN" \ -H "Content-Type: application/json" \ -d '{}' ``` ## Example response (201) ```json { "order": { "id": 7, "assigned_admin": null, "battery_declaration_link": "", "broker_address": null, "ccd_status": "ccd_not_required", "commercial_invoice_link": "", "created_at": "2026/10/23 07:14:46 UTC", "customer_reference": null, "customs_clearance_document_link": "", "date_delivered": null, "description_of_contents": null, "destination_address": { "id": 3, "address_1": "Destination Address 1", "address_2": "aa", "address_3": "aa", "city": "aa", "classification": "business", "company": "aa", "country": { "id": 5, "default_postal_code": null, "dhl_export_code": null, "dhl_import_code": null, "dhl_tax_code": null, "export_code_label": "Export Number", "import_code_label": "Importer Code", "iso_code_2": "ISO5", "iso_code_3": "ISO5", "name": "random", "postal_code_required": true, "tax_number_label": "Tax Number", "vat_rate": 0.17 }, "country_id": 5, "email": "aa@aa.com", "import_code": "Import code Destination", "latitude": null, "longitude": null, "name": "aa", "phone": "MyString", "postal_code": "aa", "province": "aa", "summary": "random", "tax_number": null, "time_zone_id": null }, "draft_bill_of_lading_link": "", "eei_eligible": false, "eei_request_document_link": "", "export_permit_link": "", "final_bill_of_lading_link": "", "importer_of_record_address": null, "internal_transaction_number": null, "invoice_data": { "billable_weights": { "metric": { "packages": 0, "mass_unit": "kg", "distance_unit": "cm", "volumetric_weight": 0, "weight": 0, "billable_weight": 0, "volume": 0 }, "imperial": { "packages": 0, "mass_unit": "lb", "distance_unit": "inches", "volumetric_weight": 0, "weight": 0, "billable_weight": 0, "volume": 0 } }, "estimate_id": 7, "line_items": [], "quote_expired": false, "shipping_company": "ShippingCo1", "shipping_service": "Express" }, "invoice_number": null, "materials_safety_data_sheet_link": "", "measured_weight": 0, "origin_address": { "id": 2, "address_1": "Origin Address 1", "address_2": "aa", "address_3": "aa", "city": "aa", "classification": "business", "company": "aa", "country": { "id": 3, "default_postal_code": null, "dhl_export_code": null, "dhl_import_code": null, "dhl_tax_code": null, "export_code_label": "Export Number", "import_code_label": "Importer Code", "iso_code_2": "ISO3", "iso_code_3": "ISO3", "name": "random", "postal_code_required": true, "tax_number_label": "Tax Number", "vat_rate": 0.17 }, "country_id": 3, "email": "aa@aa.com", "import_code": "Import code Origin", "latitude": null, "longitude": null, "name": "aa", "phone": "MyString", "postal_code": "aa", "province": "aa", "summary": "random", "tax_number": null, "time_zone_id": null }, "packaging_list_link": "", "pickup_date": "2026-10-23", "pickup_instructions": "", "proof_of_delivery_link": "", "purpose_of_shipment_id": 26, "quote_id": 7, "reference_number": "MYSABC001000001", "scheduled_pickup": "", "send_consignee_tracking_details": false, "shipments": [ { "shipping_service": "Express", "status": "order_received", "tracking_link": null, "waybill": null, "waybill_document_link": "" } ], "shippers_letter_of_instruction_link": "", "status": "order_received", "stream_packing_list_link": "", "tracking_link": null, "value_of_goods": 100, "value_of_goods_currency": "USD", "waybill": null, "waybill_document_link": "" } } ``` --- # List order ids by status `GET /client_api/v2/orders_by_status` The ids of your company's orders that have a shipment in the given status. Read each one with Get an order. ## Parameters - `status` (string): A shipment status, such as `in_transit`. List order statuses has every value. ## Returns Returns a list of order ids. - `order_ids` (array of integer, required): The ids of the matching orders, each once. ## Errors - `401 Unauthorized`: The token is missing, expired or invalid. Sign in again. ## Example request (curl) ```bash curl -X GET "https://sandbox-api.vatit-stream.com/client_api/v2/orders_by_status?status=in_transit" \ -H "Authorization: Bearer $API_TOKEN" ``` ## Example response (200) ```json { "order_ids": [ 14 ] } ``` --- # List purposes of shipment `GET /client_api/v2/purpose_of_shipments` The incoterms your company may quote with. A quote's and an order's `purpose_of_shipment_id` comes from here. ## Returns Returns a list of purpose of shipments. - `purpose_of_shipments` (array of objects, required): The purposes of shipment on this page. - `id` (integer, required): The purpose's id, for a quote's or order's `purpose_of_shipment_id`. - `code` (string, required): The incoterm's code, such as `DDP` or `DAP`. - `description` (string, required): The incoterm's name. - `explanation` (object, nullable, required): What the incoterm means for who pays what. Often empty. - `meta` (object, required): How many pages and records the list has. - `page_count` (integer, required): How many pages the list has. Ask for another with `?page=`. - `record_count` (integer, required): How many records the list has across all pages. ## Errors - `401 Unauthorized`: The token is missing, expired or invalid. Sign in again. ## Example request (curl) ```bash curl -X GET "https://sandbox-api.vatit-stream.com/client_api/v2/purpose_of_shipments" \ -H "Authorization: Bearer $API_TOKEN" ``` ## Example response (200) ```json { "purpose_of_shipments": [ { "id": 22, "code": "SALE", "description": "Sale of goods", "explanation": null } ], "meta": { "page_count": 1, "record_count": 1 } } ``` --- # Create a quote `POST /client_api/v2/quotes` Describe the shipment, and we price it with each carrier that can take it. Each estimate in the answer can be booked with Create an order. ## Body - `purpose_of_shipment_id` (integer, required): The incoterm the goods move under, which settles who pays duties and taxes. Take the id from List purposes of shipment. Ids differ between the sandbox and production. - `reason_for_shipment_id` (integer): Why the goods are moving, for customs. Take the id from List reasons for shipment. Left out, we use documents for a document shipment and our default reason for anything else. Ids differ between the sandbox and production. - `value_of_goods` (integer, required): What the goods are worth in total, at least 1. Customs duties and insurance are worked out from it. - `value_of_goods_currency_id` (string): The currency of `value_of_goods` and of each item's value, as a three-letter code from List currencies. - `description_of_contents` (string): What is in the shipment, in a few words a customs officer understands. At most 70 characters. - `mass_unit` (enum, required): The unit every weight in this request is in. Possible enum values: `kg`, `lb`. - `distance_unit` (enum, required): The unit every package size in this request is in. Possible enum values: `cm`, `inch`. - `is_document` (boolean): `true` when the shipment holds only papers. Documents need no items declared. - `is_stackable` (boolean): `true` when other freight may be stacked on top of the packages. - `is_liftgate_required` (boolean): `true` when the vehicle needs a lift to load or unload, because there is no loading dock. - `is_shipment_protection_required` (boolean): `true` to insure the goods for their declared value. - `origin_address` (object): Where the carrier collects the goods. Needed to price the shipment. - `name` (string): The person to ask for. At most 35 characters. - `company` (string): The company at the address. At most 35 characters. - `address_1` (string): The street address. At most 34 characters. - `address_2` (string): A second address line, such as a floor or unit. At most 34 characters. - `city` (string): The city or town. At most 20 characters. - `province` (string): The province, state or county. - `postal_code` (string): The postal code. Some countries, such as Ireland, refuse an address without one. - `country_id` (integer, required): The country. Take the id from List countries. Ids differ between the sandbox and production. - `email` (string): An email address for the person at the address. Carriers use it for delivery notices. - `phone` (string): A phone number for the person at the address. At most 15 characters. - `classification` (enum): Whether the address is a business or a home. Carriers charge more to deliver to a home. Possible enum values: `business`, `residential`. - `destination_address` (object): Where the goods are delivered. Needed to price the shipment. - `name` (string): The person to ask for. At most 35 characters. - `company` (string): The company at the address. At most 35 characters. - `address_1` (string): The street address. At most 34 characters. - `address_2` (string): A second address line, such as a floor or unit. At most 34 characters. - `city` (string): The city or town. At most 20 characters. - `province` (string): The province, state or county. - `postal_code` (string): The postal code. Some countries, such as Ireland, refuse an address without one. - `country_id` (integer, required): The country. Take the id from List countries. Ids differ between the sandbox and production. - `email` (string): An email address for the person at the address. Carriers use it for delivery notices. - `phone` (string): A phone number for the person at the address. At most 15 characters. - `classification` (enum): Whether the address is a business or a home. Carriers charge more to deliver to a home. Possible enum values: `business`, `residential`. - `packages` (array of objects): Each box or pallet in the shipment. Needed to price the shipment. - `weight` (number, required): What the package weighs, in `mass_unit`. - `length` (integer, required): The package's length, in `distance_unit`. - `width` (integer, required): The package's width, in `distance_unit`. - `height` (integer, required): The package's height, in `distance_unit`. - `hs_codes` (array of objects): Each kind of item in the shipment, as customs sees it. Leave out for a document shipment. - `code` (string, required): The item's tariff code (HS code), at least six digits. - `country_id` (integer, required): The country the item was made in. Take the id from List countries. Ids differ between the sandbox and production. - `description` (string, required): What the item is, in plain words. At most 250 characters. - `quantity` (integer): How many of this item are in the shipment. - `item_value` (number, required): What one item is worth, in `value_of_goods_currency_id`. - `item_mass` (number, required): What one item weighs, in `mass_unit`. ## Returns Returns the quote. - `quote` (object, required): The quote. - `id` (integer, required): The quote's id. - `dirty` (boolean, required): Always `false`. Nothing sets it. - `errors` (array of values, required): Why a carrier could not price the shipment, one message per carrier that refused. Empty when every carrier priced it. - `estimate_taxes_and_duties` (boolean, required): `true` when the estimates include the destination's duties and taxes. - `estimates` (array of objects, required): One estimate per carrier service that could take the shipment. Book one with Create an order. - `billable_weights` (object, required): The weights the carrier charges on, in metric and in imperial units. - `metric` (object, required): The weights in kilograms, the sizes in centimetres and the volume in cubic metres. - `packages` (integer, required): How many packages there are. - `mass_unit` (string, required): Always `kg`. - `distance_unit` (string, required): Always `cm`. - `volumetric_weight` (number, required): The weight the carrier works out from the packages' size. - `weight` (number, required): What the packages weigh together. - `billable_weight` (number, required): The weight the carrier charges on, the larger of `weight` and `volumetric_weight`. - `volume` (number, required): The packages' volume together. - `imperial` (object, required): The weights in pounds, the sizes in inches and the volume in cubic feet. - `packages` (integer, required): How many packages there are. - `mass_unit` (string, required): Always `lb`. - `distance_unit` (string, required): Always `inches`. A request spells the same unit `inch`. - `volumetric_weight` (number, required): The weight the carrier works out from the packages' size. - `weight` (number, required): What the packages weigh together. - `billable_weight` (number, required): The weight the carrier charges on, the larger of `weight` and `volumetric_weight`. - `volume` (number, required): The packages' volume together. - `estimate_id` (integer, required): The estimate's id. Book it by sending it as an order's `quote_estimate_id`. - `line_items` (array of objects, required): What the price is made of, one charge per line. - `cost` (number, required): What the charge costs, in `currency_id`. - `currency_id` (string, required): The currency the company is billed in. - `description` (string, required): The charge, such as freight or fuel surcharge. - `quote_expired` (boolean, required): `true` when this price no longer holds, because another estimate was booked or the shipment changed. Get a new quote. - `shipping_company` (string, required): The carrier. - `shipping_service` (string, required): The carrier's service, such as International Priority. - `hub_transit` (boolean, required): `true` when the shipment goes through one of our hubs on the way. ## Errors - `400 Bad Request`: The request body isn't valid JSON, or something failed on our side. - `401 Unauthorized`: The token is missing, expired or invalid. Sign in again. - `422 Unprocessable Content`: The request was refused. `error` says why in one sentence, and `errors` lists each reason. - `429 Too Many Requests`: Too many requests. Wait a little and try again. ## Example request (curl) ```bash curl -X POST "https://sandbox-api.vatit-stream.com/client_api/v2/quotes" \ -H "Authorization: Bearer $API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "purpose_of_shipment_id": 73, "reason_for_shipment_id": 45, "value_of_goods": 18500, "value_of_goods_currency_id": "ZAR", "description_of_contents": "Cotton shirts and denim trousers", "mass_unit": "kg", "distance_unit": "cm", "is_document": false, "is_stackable": true, "is_liftgate_required": false, "is_shipment_protection_required": false, "origin_address": { "name": "Thandi Mokoena", "company": "Global Trade Corp", "address_1": "14 Bree Street", "address_2": "Unit 3", "city": "Cape Town", "province": "Western Cape", "postal_code": "8001", "country_id": 23, "email": "dispatch@globaltradecorp.example", "phone": "+27 21 555 0142", "classification": "business" }, "destination_address": { "name": "Oliver Bennett", "company": "Bennett & Hale Ltd", "address_1": "221 Shoreditch High Street", "address_2": "Floor 2", "city": "London", "province": "Greater London", "postal_code": "E1 6PJ", "country_id": 24, "email": "goods-in@bennetthale.example", "phone": "+44 20 7946 0321", "classification": "business" }, "packages": [ { "weight": 12.5, "length": 60, "width": 40, "height": 35 } ], "hs_codes": [ { "code": "620342", "country_id": 23, "description": "Men'\''s cotton trousers", "quantity": 40, "item_value": 250, "item_mass": 0.2 }, { "code": "620520", "country_id": 23, "description": "Men'\''s cotton shirts", "quantity": 60, "item_value": 141.67, "item_mass": 0.075 } ] }' ``` ## Example response (201) ```json { "quote": { "id": 39, "dirty": false, "errors": [], "estimate_taxes_and_duties": false, "estimates": [ { "billable_weights": { "metric": { "packages": 1, "mass_unit": "kg", "distance_unit": "cm", "volumetric_weight": 16.8, "weight": 12.5, "billable_weight": 16.8, "volume": 0.084 }, "imperial": { "packages": 1, "mass_unit": "lb", "distance_unit": "inches", "volumetric_weight": 37.04, "weight": 27.56, "billable_weight": 37.04, "volume": 2.9664316254643865 } }, "estimate_id": 34, "line_items": [ { "cost": 2184.5, "currency_id": "ZAR", "description": "Freight" }, { "cost": 393.21, "currency_id": "ZAR", "description": "Fuel surcharge" }, { "cost": 450, "currency_id": "ZAR", "description": "Customs clearance" } ], "quote_expired": false, "shipping_company": "FedEx", "shipping_service": "International Priority" } ], "hub_transit": false } } ``` --- # Get a quote `GET /client_api/v2/quotes/{id}` Read a quote again, with its estimates. ## Parameters - `id` (integer, required): The quote's id, from Create a quote. ## Returns Returns the quote. - `quote` (object, required): The quote. - `id` (integer, required): The quote's id. - `dirty` (boolean, required): Always `false`. Nothing sets it. - `errors` (array of values, required): Why a carrier could not price the shipment, one message per carrier that refused. Empty when every carrier priced it. - `estimate_taxes_and_duties` (boolean, required): `true` when the estimates include the destination's duties and taxes. - `estimates` (array of objects, required): One estimate per carrier service that could take the shipment. Book one with Create an order. - `billable_weights` (object, required): The weights the carrier charges on, in metric and in imperial units. - `metric` (object, required): The weights in kilograms, the sizes in centimetres and the volume in cubic metres. - `packages` (integer, required): How many packages there are. - `mass_unit` (string, required): Always `kg`. - `distance_unit` (string, required): Always `cm`. - `volumetric_weight` (number, required): The weight the carrier works out from the packages' size. - `weight` (number, required): What the packages weigh together. - `billable_weight` (number, required): The weight the carrier charges on, the larger of `weight` and `volumetric_weight`. - `volume` (number, required): The packages' volume together. - `imperial` (object, required): The weights in pounds, the sizes in inches and the volume in cubic feet. - `packages` (integer, required): How many packages there are. - `mass_unit` (string, required): Always `lb`. - `distance_unit` (string, required): Always `inches`. A request spells the same unit `inch`. - `volumetric_weight` (number, required): The weight the carrier works out from the packages' size. - `weight` (number, required): What the packages weigh together. - `billable_weight` (number, required): The weight the carrier charges on, the larger of `weight` and `volumetric_weight`. - `volume` (number, required): The packages' volume together. - `estimate_id` (integer, required): The estimate's id. Book it by sending it as an order's `quote_estimate_id`. - `line_items` (array of objects, required): What the price is made of, one charge per line. - `cost` (number, required): What the charge costs, in `currency_id`. - `currency_id` (string, required): The currency the company is billed in. - `description` (string, required): The charge, such as freight or fuel surcharge. - `quote_expired` (boolean, required): `true` when this price no longer holds, because another estimate was booked or the shipment changed. Get a new quote. - `shipping_company` (string, required): The carrier. - `shipping_service` (string, required): The carrier's service, such as International Priority. - `hub_transit` (boolean, required): `true` when the shipment goes through one of our hubs on the way. ## Errors - `401 Unauthorized`: The token is missing, expired or invalid. Sign in again. ## Example request (curl) ```bash curl -X GET "https://sandbox-api.vatit-stream.com/client_api/v2/quotes/40" \ -H "Authorization: Bearer $API_TOKEN" ``` ## Example response (200) ```json { "quote": { "id": 40, "dirty": false, "errors": [], "estimate_taxes_and_duties": false, "estimates": [ { "billable_weights": { "metric": { "packages": 1, "mass_unit": "kg", "distance_unit": "cm", "volumetric_weight": 16.8, "weight": 12.5, "billable_weight": 16.8, "volume": 0.084 }, "imperial": { "packages": 1, "mass_unit": "lb", "distance_unit": "inches", "volumetric_weight": 37.04, "weight": 27.56, "billable_weight": 37.04, "volume": 2.9664316254643865 } }, "estimate_id": 35, "line_items": [ { "cost": 2184.5, "currency_id": "ZAR", "description": "Freight" }, { "cost": 393.21, "currency_id": "ZAR", "description": "Fuel surcharge" }, { "cost": 450, "currency_id": "ZAR", "description": "Customs clearance" } ], "quote_expired": false, "shipping_company": "FedEx", "shipping_service": "International Priority" } ], "hub_transit": false } } ``` --- # List reasons for shipment `GET /client_api/v2/reason_for_shipments` Why goods can be moving, for customs. A quote's `reason_for_shipment_id` comes from here. ## Returns Returns a list of reason for shipments. - `reason_for_shipments` (array of objects, required): The reasons for shipment, by name. - `id` (integer, required): The reason's id, for a quote's `reason_for_shipment_id`. - `enabled` (boolean, required): Whether the reason is switched on. - `name` (string, required): The reason, as customs sees it. - `product_identifiers_required` (boolean, required): `true` when each item needs a product code, such as a SKU, model number or barcode. - `return` (boolean, required): `true` when the goods are coming back, for example after a repair. - `sort_index` (integer, required): Where the reason sits in a list shown to people. ## Errors - `401 Unauthorized`: The token is missing, expired or invalid. Sign in again. ## Example request (curl) ```bash curl -X GET "https://sandbox-api.vatit-stream.com/client_api/v2/reason_for_shipments" \ -H "Authorization: Bearer $API_TOKEN" ``` ## Example response (200) ```json { "reason_for_shipments": [ { "id": 9, "enabled": true, "name": "Commercial sale", "product_identifiers_required": true, "return": false, "sort_index": 1 }, { "id": 2, "enabled": true, "name": "Documents", "product_identifiers_required": false, "return": false, "sort_index": 3 }, { "id": 1, "enabled": true, "name": "Gift", "product_identifiers_required": false, "return": false, "sort_index": 2 }, { "id": 10, "enabled": true, "name": "Return for repair", "product_identifiers_required": true, "return": false, "sort_index": 4 } ] } ``` --- # Get a setting `GET /client_api/v2/system_configs/{id}` Reads one of our settings that a client may see. The answer's shape depends on the setting. ## Parameters - `id` (string, required): The setting's name. A client may read `document_descriptions`, `commercial_invoice_placeholders`, `broker_optional_channels`, `bill_of_lading_applicable_shipping_company_ids`, `export_permit_origin_country_ids`, `whats_new_client_ui` and `whats_new_reseller_ui`. ## Returns Returns a list. ## Errors - `401 Unauthorized`: The token is missing, expired or invalid. Sign in again. ## Example request (curl) ```bash curl -X GET "https://sandbox-api.vatit-stream.com/client_api/v2/system_configs/document_descriptions" \ -H "Authorization: Bearer $API_TOKEN" ``` ## Example response (200) ```json [ "Commercial invoice", "Packing list" ] ``` --- # Create a webhook `POST /client_api/v2/webhooks` Registers a URL that we send a POST to whenever one of the chosen events happens. ## Body - `webhook` (object, required): The webhook's settings. - `target_url` (string, required): The http or https URL we send events to. - `events` (array of string): The events to send. `shipment.updated.status` fires when a shipment's status changes. `shipment.updated.waybill` fires when a shipment gets its waybill. Possible enum values: `shipment.updated.status`, `shipment.updated.waybill`. ## Returns Returns the webhook. - `webhook` (object, required): The webhook. - `events` (array of string, required): The events to send. `shipment.updated.status` fires when a shipment's status changes. `shipment.updated.waybill` fires when a shipment gets its waybill. Possible enum values: `shipment.updated.status`, `shipment.updated.waybill`. - `id` (integer, required): The webhook's id. - `status` (enum, required): `failing` when deliveries to the URL keep failing. Possible enum values: `active`, `failing`. - `target_url` (string, required): The http or https URL we send events to. - `token` (string, required): A secret we send with every event, so your system can tell the event came from us. ## Errors - `400 Bad Request`: The request body isn't valid JSON, or something failed on our side. - `401 Unauthorized`: The token is missing, expired or invalid. Sign in again. - `422 Unprocessable Content`: The request was refused. `error` says why in one sentence, and `errors` lists each reason. ## Example request (curl) ```bash curl -X POST "https://sandbox-api.vatit-stream.com/client_api/v2/webhooks" \ -H "Authorization: Bearer $API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "webhook": { "target_url": "https://hooks.globaltradecorp.example/stream", "events": [ "shipment.updated.status", "shipment.updated.waybill" ] } }' ``` ## Example response (201) ```json { "webhook": { "events": [ "shipment.updated.status", "shipment.updated.waybill" ], "id": 3, "status": "active", "target_url": "https://hooks.globaltradecorp.example/stream", "token": "q7Vt2mX9pL4sKe8RzW1nYg" } } ``` --- # Delete a webhook `DELETE /client_api/v2/webhooks/{id}` Stops the webhook. We send it nothing more. ## Parameters - `id` (integer, required): The webhook's id. ## Returns Returns the result. - `success` (boolean, required): Always `false` on an error. A successful delete answers `true`. - `error` (string, required): What went wrong, in one sentence. Empty on success. - `errors` (array of values, required): Each reason the request was refused, one per entry. Often empty, in which case `error` says it all. ## Errors - `401 Unauthorized`: The token is missing, expired or invalid. Sign in again. ## Example request (curl) ```bash curl -X DELETE "https://sandbox-api.vatit-stream.com/client_api/v2/webhooks/2" \ -H "Authorization: Bearer $API_TOKEN" ``` ## Example response (200) ```json { "success": true, "error": "", "errors": [] } ``` --- # Get a webhook `GET /client_api/v2/webhooks/{id}` ## Parameters - `id` (integer, required): The webhook's id. ## Returns Returns the webhook. - `webhook` (object, required): The webhook. - `events` (array of string, required): The events to send. `shipment.updated.status` fires when a shipment's status changes. `shipment.updated.waybill` fires when a shipment gets its waybill. Possible enum values: `shipment.updated.status`, `shipment.updated.waybill`. - `id` (integer, required): The webhook's id. - `status` (enum, required): `failing` when deliveries to the URL keep failing. Possible enum values: `active`, `failing`. - `target_url` (string, required): The http or https URL we send events to. - `token` (string, required): A secret we send with every event, so your system can tell the event came from us. ## Errors - `401 Unauthorized`: The token is missing, expired or invalid. Sign in again. ## Example request (curl) ```bash curl -X GET "https://sandbox-api.vatit-stream.com/client_api/v2/webhooks/1" \ -H "Authorization: Bearer $API_TOKEN" ``` ## Example response (200) ```json { "webhook": { "events": [ "shipment.updated.status", "shipment.updated.waybill" ], "id": 1, "status": "active", "target_url": "https://hooks.globaltradecorp.example/stream", "token": "q7Vt2mX9pL4sKe8RzW1nYg" } } ``` --- # Update a webhook `PUT /client_api/v2/webhooks/{id}` Changes a webhook's URL or events. Send only what changes. PATCH works the same way. ## Parameters - `id` (integer, required): The webhook's id. ## Body - `webhook` (object, required): The webhook's settings. - `events` (array of string): The events to send. `shipment.updated.status` fires when a shipment's status changes. `shipment.updated.waybill` fires when a shipment gets its waybill. Possible enum values: `shipment.updated.status`, `shipment.updated.waybill`. ## Returns Returns the webhook. - `webhook` (object, required): The webhook. - `events` (array of string, required): The events to send. `shipment.updated.status` fires when a shipment's status changes. `shipment.updated.waybill` fires when a shipment gets its waybill. Possible enum values: `shipment.updated.status`, `shipment.updated.waybill`. - `id` (integer, required): The webhook's id. - `status` (enum, required): `failing` when deliveries to the URL keep failing. Possible enum values: `active`, `failing`. - `target_url` (string, required): The http or https URL we send events to. - `token` (string, required): A secret we send with every event, so your system can tell the event came from us. ## Errors - `400 Bad Request`: The request body isn't valid JSON, or something failed on our side. - `401 Unauthorized`: The token is missing, expired or invalid. Sign in again. - `422 Unprocessable Content`: The request was refused. `error` says why in one sentence, and `errors` lists each reason. ## Example request (curl) ```bash curl -X PUT "https://sandbox-api.vatit-stream.com/client_api/v2/webhooks/5" \ -H "Authorization: Bearer $API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "webhook": { "events": [ "shipment.updated.status" ] } }' ``` ## Example response (200) ```json { "webhook": { "events": [ "shipment.updated.status" ], "id": 4, "status": "active", "target_url": "https://hooks.globaltradecorp.example/stream", "token": "q7Vt2mX9pL4sKe8RzW1nYg" } } ```