# Generate an air waybill PDF (POST /v1/documents/waybill)

> POST /v1/documents/waybill: Generate an air waybill PDF. border.bot API reference (Shipping documents).

Source: https://staging.border.bot/docs/api/create-air-waybill

> Documentation index: https://staging.border.bot/llms.txt. Every page is Markdown at its URL + `.md`.

`POST https://staging-api.border.bot/v1/documents/waybill`

Requires an API key (`Authorization: Bearer bb_live_…`).

A master or house air waybill on the IATA Resolution 600a face, with the Resolution 600b conditions of contract after each copy (`conditions`), as 3 originals or the full set of 8 (`copies`). Validated before charging: a wrong check digit or non-Latin text answers 400 without a charge. The PDF is an unsigned draft until the issuing carrier or its agent executes it, and acceptance by any airline, agent or authority is not guaranteed: use is subject to the Terms’ Shipping documents section (https://border.bot/legal/terms#shipping-documents). Costs 1 credit.

API key scope: `documents`.

## Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `idempotency-key` | string | no | Make retries safe: a repeat with the same key returns the original result without charging again (keys are scoped to your workspace). |

## Request body (JSON)

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `kind` | "master" \| "house" | no |  |
| `prefix` | string | no |  |
| `number` | string | yes |  |
| `masterNumber` | string | no |  |
| `shipper` | object | yes |  |
| `consignee` | object | yes |  |
| `issuer` | object | yes |  |
| `agent` | object | no |  |
| `accountingInformation` | string | no |  |
| `departure` | string | yes |  |
| `departureName` | string | no |  |
| `destination` | string | yes |  |
| `destinationName` | string | no |  |
| `routing` | object[] | no |  |
| `firstCarrierName` | string | no |  |
| `flights` | string[] | no |  |
| `referenceNumber` | string | no |  |
| `optionalShippingInformation` | string | no |  |
| `currency` | string | yes |  |
| `weightValuation` | "PP" \| "CC" | no |  |
| `otherChargesPaid` | "PP" \| "CC" | no |  |
| `declaredValueCarriage` | number | no |  |
| `declaredValueCustoms` | number | no |  |
| `insurance` | number | no |  |
| `handlingInformation` | string | no |  |
| `sci` | string | no |  |
| `weightUnit` | "kg" \| "lb" | no |  |
| `dimensionUnit` | "cm" \| "in" | no |  |
| `volumeDivisor` | integer | no |  |
| `lines` | object[] | yes |  |
| `otherCharges` | object[] | no |  |
| `valuationCharge` | number | no |  |
| `tax` | number | no |  |
| `shipperSignature` | string | no |  |
| `executedOn` | string (date) | yes |  |
| `executedAt` | string | yes |  |
| `carrierSignature` | string | no |  |
| `copies` | "originals" \| "full" | no |  |
| `conditions` | boolean | no |  |

## Responses

- `200`: The PDF (base64) and the credits charged. (`AirWaybillResponse`)
- `400`: Invalid input (`invalid_input`). (`Error`)
- `401`: Missing, invalid, revoked or expired API key (`unauthorized`). (`Error`)
- `402`: Not enough credits (`insufficient_credits`). Nothing was charged. (`Error`)
- `403`: Workspace suspended, action disabled, or the key lacks the scope (`org_suspended`, `action_disabled`, `forbidden`). (`Error`)
- `409`: A request with this Idempotency-Key is still in progress (`conflict`). (`Error`)
- `429`: Rate limited (`rate_limited`). Retry after `Retry-After` seconds; `RateLimit` says which limit was hit (`r=0`, `t` seconds until its window ends) and `RateLimit-Policy` its quota. (`Error`)
- `500`: Unexpected error (`internal`). (`Error`)
- `502`: The engine failed (`upstream_error`). The credits are refunded automatically. (`Error`)
- `504`: The engine timed out (`upstream_timeout`). The credits are refunded automatically. (`Error`)

## Example

```bash
curl -X POST 'https://staging-api.border.bot/v1/documents/waybill' \
  -H 'Authorization: Bearer bb_live_...' \
  -H 'Content-Type: application/json' \
  -d '{"kind":"master","prefix":"125","number":"12345675","shipper":{"name":"Northwind Apparel Ltd","address":"Unit 4, Bath Road Trading Estate","city":"Hounslow","postcode":"TW4 6HG","country":"GB","phone":"+44 20 7946 0000"},"consignee":{"name":"Harbor Street Retail Inc","address":"1200 Harbor Street, Suite 300","city":"Los Angeles","postcode":"CA 90021","country":"US","phone":"+1 213 555 0100"},"issuer":{"name":"British Airways World Cargo","address":"Heathrow Airport, Hounslow TW6 2JS"},"agent":{"name":"Skyline Forwarding Ltd","city":"London","iataCode":"91-4 7712/0010"},"accountingInformation":"FREIGHT PREPAID","departure":"LHR","departureName":"London Heathrow","destination":"LAX","destinationName":"Los Angeles","routing":[{"to":"LAX","by":"BA"}],"firstCarrierName":"British Airways","flights":["BA0283/14OCT"],"currency":"GBP","weightValuation":"PP","otherChargesPaid":"PP","handlingInformation":"NOTIFY CONSIGNEE ON ARRIVAL. COMMERCIAL INVOICE AND PACKING LIST ATTACHED.","sci":"X","lines":[{"pieces":4,"grossWeight":86.4,"rateClass":"Q","rate":3.85,"description":"Cotton knitted T-shirts and hoodies, 480 units","hsCodes":["610910","611020"],"dimensions":[{"pieces":4,"length":60,"width":40,"height":45}]}],"otherCharges":[{"code":"AW","dueTo":"A","amount":25},{"code":"MY","dueTo":"C","amount":51.84},{"code":"SC","dueTo":"C","amount":12.96}],"shipperSignature":"Skyline Forwarding Ltd","executedOn":"2026-10-13","executedAt":"London","copies":"originals","conditions":true}'
```