# 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://border.bot/docs/api/create-air-waybill

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

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

Requires an access token from an API client (`Authorization: Bearer <access_token>`).

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 client 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 or expired access token, or a revoked or expired API client (`unauthorized`). (`Error`)
- `402`: Not enough credits (`insufficient_credits`). Nothing was charged. (`Error`)
- `403`: Workspace suspended, action disabled, or the client 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 request

```bash
curl -X POST https://api.border.bot/v1/documents/waybill \
  -H "Authorization: Bearer $BORDERBOT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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
  }'
```

```javascript
const response = await fetch('https://api.border.bot/v1/documents/waybill', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BORDERBOT_TOKEN}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    "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
  }),
});
const data = await response.json();
```

```python
import os, uuid

import requests

response = requests.post(
    "https://api.border.bot/v1/documents/waybill",
    headers={"Authorization": f"Bearer {os.environ['BORDERBOT_TOKEN']}", "Idempotency-Key": str(uuid.uuid4())},
    json={
        "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,
    },
)
data = response.json()
```

```php
<?php
$ch = curl_init('https://api.border.bot/v1/documents/waybill');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('BORDERBOT_TOKEN'),
        'Content-Type: application/json',
        'Idempotency-Key: ' . bin2hex(random_bytes(16)),
    ],
    CURLOPT_POSTFIELDS => json_encode([
        '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,
    ]),
]);
$data = json_decode(curl_exec($ch), true);
```

## Example response (200)

```json
{
  "data": {
    "number": "125-1234 5675",
    "filename": "AWB-125-12345675.pdf",
    "pages": 6,
    "contentType": "application/pdf",
    "pdf": "string"
  },
  "credits": {
    "charged": 0,
    "remaining": 0,
    "usageId": "string"
  },
  "replayed": false
}
```