V1 · Overview

Merchant API

Connect your own system (a website, a warehouse system, a script) to your shipping company. Everything you can do in the merchant portal, you can do through this API: create customers and orders, get a price, dispatch, print labels, track shipments, and read your wallet and settlements.

Quick start

1. In the merchant portal, open Integrations and create an Application. You get a client ID and a client secret. The secret is shown once, so copy it.
2. Exchange them for an access token with Get token. Get token
3. Send the token on every other call in the Authorization header.
4. Every new Application starts in Demo mode. Build and test there, then ask your shipping company to move it to Live.

curl -X POST "https://api.swiftazu.com/v1/oauth/token" \
  -H "Content-Type: application/json" \
  -d '{ "client_id": "app_f4161f3498e4205e316202cd", "client_secret": "YOUR_CLIENT_SECRET" }'

curl "https://api.swiftazu.com/v1/orders?page=1&pageSize=25" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Base address

All paths in these docs start at this address. Use HTTPS only.

If your shipping company uses its own brand and domains, your Application has its own API address. The Application screen in the merchant portal shows the exact address to call. Both addresses serve the same API.

Authentication

Get token is the only call that takes the client ID and client secret, and the only one that needs no token. The token lasts one hour. There is no refresh token: when it expires, get a new one the same way.

There are no scopes. A valid token reaches every endpoint, and only your own merchant account's data.

Demo and Live

In Demo mode the API behaves exactly as in Live: the same checks, the same answers, real prices and a real label. But a demo order costs nothing, and no driver is ever sent for it.

• A demo Application can create a limited number of orders (25 by default). Your shipping company can raise it. Past the limit, creating an order returns demo_allowance_exhausted.
• Every demo order carries isDemo: true, and its air waybill number starts with DEMO.
• Use Advance demo order to move a demo order through its journey and test your handling of each status.

Store ID

Safe retries (Idempotency-Key)

Calls that create a shipment or move money accept an Idempotency-Key header: Create order, Create orders in bulk, Dispatch order, Dispatch in bulk and Create return. Send your own unique value with the call. If the network fails and you send the same call again with the same key, you get the first result back and nothing happens twice.

Rate limits

Each Application may make 100 calls a minute. Your shipping company can raise this for an Application. Every answer tells you where you stand:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 83
X-RateLimit-Reset: 1790908310

• X-RateLimit-Limit The number of calls allowed per minute.
• X-RateLimit-Remaining The calls left in the current minute.
• X-RateLimit-Reset When the allowance is full again, as a Unix time in seconds (UTC).

Lists and pages

Formats

• Money is a text value with two decimals ("27.80"), always in your shipping company's one currency, which is returned beside it.
• Dates and times are ISO 8601 in UTC ("2026-10-02T02:30:51.260Z").
• Sizes are in centimetres and weights in kilograms.
• Records are addressed by their id (a UUID). An order also has a short Order ID for people (orderId) and, once dispatched, an air waybill number (awbNumber).
• Fields you send that the API does not know are ignored. New fields may be added to answers at any time, so ignore fields you do not know.

Errors

An error always has the same shape. Use code in your program and show message to a person. A request that fails validation also lists each problem in details.

{
  "code": "validation_failed",
  "message": "The request is not valid.",
  "details": [
    "paymentMode must be one of the following values: prepaid, cod",
    "boxes must contain at least 1 elements"
  ]
}

Errors any call can return

Versions

Webhooks

To be told when something happens instead of asking, set a webhook address on your Application.

All endpoints