# Cargobase API — Autonomous Agent Implementation Guide

> **FOR:** AI coding agents that must discover, implement, test, and debug Cargobase **partner** HTTP APIs **without human guidance**.
> **INPUT YOU NEED FROM A HUMAN (only):** a valid API token for Sandbox or Production, and which role to target (`shipper` or `provider`). Everything else is in this file + linked OpenAPI JSON.
> **GENERATED:** 2026-10-23T03:08:44.203Z
> **STABLE DOWNLOAD:** `/ai/cargobase-api-agent-guide.md`
> **STAFF / OPERATIONS:** separate staff-only guide via authenticated `GET /api/ai/operations-agent-guide`.

---

## Mission

Build a working integration against Cargobase partner APIs:

1. Authenticate with Token auth (`Authorization: Token <access_token>`).
2. Call the correct host (Sandbox while developing, Production at `https://pluto.cargobase.com` when you go live).
3. Use exact paths, methods, and parameter names from this document.
4. Send/receive JSON as specified.
5. Handle errors using the status playbook and retry only when safe.
6. Prefer OpenAPI JSON as the schema source of truth when a field is ambiguous.

Do **not** invent endpoints, rename path parameters, invent auth schemes, or guess enum values.

---

## Hard rules (non-negotiable)

1. **Base URL**
   - Sandbox: `https://sandbox.cargobase.com`
   - Production: `https://pluto.cargobase.com`
2. **Auth header (partner APIs):**
   ```http
   Authorization: Token <access_token>
   Accept: application/json
   Content-Type: application/json
   ```
   `Bearer <access_token>` is an alternate where the OAS lists BearerAuth.
3. **Path prefix:** partner REST paths start with `/api/1/` — never `/api/v1/`.
4. **Parameter names are exact** — do not invent aliases.
5. **Reference formats:** drafts `SD…`, shipments `S…`, quotes `Q…`, quick requests `QR…`.
6. **One resource per request**.
7. **Staff Operations** — out of scope here; use the staff Operations agent guide.
8. Prefer **`quick-request-order`** schemas for `POST /api/1/order/create/`.
9. **Webhooks are inverted:** Cargobase calls your HTTPS URL.

---

## Bootstrap algorithm

```
IF missing API token: STOP (request token + sandbox|production + shipper|provider)
SET base_url + Authorization: Token …
GET {base_url}/api/1/addresses  // smoke
Implement use-cases from this guide; on error use Debugging playbook
```

---

## Self-test plan

1. Auth smoke `GET /api/1/addresses` → 2xx
2. Create/tracking/webhook flows as in scope
3. Negative: missing auth → 401
4. No `/api/4.0` in partner clients

---

## Debugging playbook

| Status | Action |
|--------|--------|
| 400 | Fix vs schema required/enum |
| 401/403 | Fix Token auth + env |
| 404 | Fix reference/path/env |
| 429 | Backoff retry |
| 5xx | Limited retry then stop with evidence pack |

Evidence pack: URL, method, status, bodies, UTC time.

---

## Machine-readable companions

| Resource | Purpose |
|----------|---------|
| `/ai/cargobase-api-agent-guide.md` | This file |
| `/llms.txt` | Discovery |
| `/oas/<id>.openapi.json` | Full contracts |

---

## Collection: `pluto` — Cargobase Pluto API

- **Audience:** Shipper & Provider partner integrations
- **OpenAPI source:** `/oas/pluto.openapi.json` (download this if you need the raw contract)
- **Servers:** `https://pluto.cargobase.com` (Production) · `https://sandbox.cargobase.com` (Sandbox)
- **Security schemes:**
  - `TokenAuth`: send header `Authorization` — value format described as: Token-based authentication (Django REST framework style). Format: `Token <access_token>` Example: `Token your_token_here`
- `BearerAuth`: http bearer

### Endpoint index

| Method | Path | Summary | Statuses |
|--------|------|---------|----------|
| `GET` | `/api/1/quickrequests/` | List view | 200 |
| `GET` | `/api/1/addresses` | List Addresses | 200, 401, 403 |
| `GET` | `/api/1/requests/draft/` | List view | 200, 401, 403 |
| `POST` | `/api/1/requests/draft/` | Create Draft | 201, 400, 401, 403 |
| `GET` | `/api/1/requests/draft/{draft_id}/` | Draft Detail | 200, 401, 403, 404 |
| `PATCH` | `/api/1/requests/draft/{draft_id}/` | Update Draft | 200, 400, 401, 403, 404 |
| `POST` | `/api/1/requests/draft/{draft_id}/attachments/` | Upload Draft Attachment | 201, 400, 401, 403, 404 |
| `POST` | `/api/1/requests/draft/{draft_id}/stops/` | Add Stop | 201, 400, 401, 403, 404 |
| `PATCH` | `/api/1/requests/draft/{draft_id}/stops/{stop_key}/` | Update Stop | 200, 400, 401, 403, 404 |
| `DELETE` | `/api/1/requests/draft/{draft_id}/stops/{stop_key}/` | Delete Stop | 204, 401, 403, 404 |
| `POST` | `/api/1/requests/draft/{draft_id}/create/` | Convert Draft | 200, 201, 400, 401, 403, 404 |
| `POST` | `/api/1/requests/create/` | Create Request | 200 |
| `GET` | `/api/1/requests/` | List view | 200, default |
| `POST` | `/api/1/quotes/` | Submit Quote | 200 |
| `GET` | `/api/1/quotes/` | Quotes List | 200 |
| `GET` | `/api/1/shipments/` | List view | 200 |
| `GET` | `/api/1/invoices/` | List view | 200 |
| `GET` | `/api/1/invoices/{invoice_reference}` | Details | 200 |
| `POST` | `/api/1/invoice-status-update/{invoice_reference}` | Update Status | 201, 400, 403, 404 |
| `GET` | `/api/1/quickrequests/{qr_reference}/` | Quick Request Detail | 200 |
| `PUT` | `/api/1/requests/{shipment_reference}/` | Update Request | 200 |
| `GET` | `/api/1/requests/{shipment_reference}/` | Request Detail | 200 |
| `PUT` | `/api/1/requests/{shipment_reference}/assign/` | Assign team | 200 |
| `PUT` | `/api/1/quotes/{quotation_reference}/` | Update Quote | 200 |
| `GET` | `/api/1/shipments/{shipment_reference}/` | Shipment Detail | 200 |
| `PUT` | `/api/1/shipments/{shipment_reference}/` | Cancel shipment | 200 |
| `POST` | `/api/1/order/create/` | Create Order | 200, 400, 401 |
| `POST` | `/api/1/carrier-tracking-webhook` | Post carrier tracking update | 200, 400, 401, 403 |
| `POST` | `/api/1/shipments/{shipment_reference}/tracking/create/` | Add tracking number | 201, 400, 401, 403, 404 |

### Operations (implement from these specs)

#### Tag: Quick Requests

#### `GET /api/1/quickrequests/`

- **summary:** List view
- **description:** The Quick Request List View end-point provides a list of Quick Requests associated with the requesting user. A Quick Request is a 'draft' version of a Quote request, therefore this end-point is only available to shippers. ## Request URI ``` GET https://pluto.cargobase.com/api/1/quickrequests/ Content-Type: application/json Authorization: Token your_token_here ```
- **statuses:** 200

**Parameters**

- `Authorization` (header) type=string example=`Token your_token_here` — Replace 'your_token_here' with your token.

**Success `200`** — Successful response

#### `GET /api/1/quickrequests/{qr_reference}/`

- **summary:** Quick Request Detail
- **description:** The Quick Request Detail end-point can be used to retrieve all specifics of a Quick request. A Quick Request is a 'draft' version of a Quote request, therefore this end-point is only available to shippers. ## Request URI ``` GET https://pluto.cargobase.com/api/1/quickrequests/`Quick_request_reference` Authorization: Token your_token_here ``` ## Status codes
- **statuses:** 200

**Parameters**

- `Authorization` (header) type=string example=`Token your_token_here` — Replace 'your_token_here' with your token.
- `qr_reference` (path, required) type=string pattern=`^QR[-\d]+$` example=`QR12345678` — Quick request reference number (e.g. `QR12345678`).

**Success `200`** — Successful response

#### `POST /api/1/order/create/`

- **operationId:** `createOrder`
- **summary:** Create Order
- **description:** Creates a new shipping order with scheduling, organizational info, and packing list.
- **statuses:** 200, 400, 401

**Request body** (required; application/json)

Schema (resolved summary):

```json
{
  "type": "object",
  "properties": {
    "quick_request": {
      "type": "object",
      "properties": {
        "title": {
          "type": "string",
          "description": "Title of the order or request",
          "example": "Shipment Title"
        },
        "comments": {
          "type": "string",
          "description": "Additional comments or instructions",
          "example": "Sample Test comments."
        },
        "external_id": {
          "type": "string",
          "description": "External ID used to identify the order in external systems",
          "example": "sample_external_id"
        }
      },
      "description": "Basic request details"
    },
    "organizational": {
      "type": "object",
      "properties": {
        "location": {
          "type": "string",
          "description": "A reference to the 'location' the request is for, location references are shared by Cargobase.",
          "example": "L1234567"
        },
        "cost_center": {
          "type": "string",
          "description": "Associated cost center",
          "example": "CC12345"
        },
        "reason_code": {
          "type": "string",
          "description": "Code explaining reason for the shipment",
          "example": "RC67890"
        },
        "reason_code_group": {
          "type": "string",
          "description": "Group categorization for reason code",
          "example": "RCG112233"
        },
        "custom_field_01": {
          "type": "string",
          "description": "User-defined custom field 1",
          "example": "Custom Value 01"
        },
        "custom_field_02": {
          "type": "string",
          "description": "User-defined custom field 2",
          "example": "Custom Value 02"
        },
        "custom_field_03": {
          "type": "string",
          "description": "User-defined custom field 3",
          "example": "Custom Value 03"
        },
        "custom_long_field_01": {
          "type": "string",
          "description": "Extended custom field",
          "example": "Custom Long Field 01"
        },
        "goods_confirmation_type": {
          "type": "string",
          "enum": [
            "Estimated",
            "Finalized"
          ],
          "example": "Finalized",
          "description": "Goods confirmation type (Estimated or Finalized)"
        }
      },
      "required": [
        "location"
      ],
      "description": "Organizational metadata for cost tracking and reporting"
    },
    "schedule": {
      "type": "object",
      "properties": {
        "pickup_contact_name": {
          "type": "string"
        },
        "pickup_contact_phone": {
          "type": "string"
        },
        "pickup_contact_email": {
          "type": "string"
        },
        "pickup_address_type": {
          "type": "string",
          "enum": [
            "Address",
            "Seaport",
            "Airport"
          ],
          "example": "Address",
          "description": "Type of pickup address (e.g. Address, Seaport or Airport)"
        },
        "pickup_address_name": {
          "type": "string",
          "description": "Name/label of pickup address",
          "example": "Main Warehouse"
        },
        "pickup_company_name": {
          "type": "string",
          "description": "Name of the pickup company",
          "example": "Logistics Co."
        },
        "pickup_city": {
          "type": "string",
          "example": "New York"
        },
        "pickup_state": {
          "type": "string",
          "example": "NY"
        },
        "pickup_country": {
          "type": "string",
          "example": "USA"
        },
        "pickup_zipcode": {
          "type": "string"
        },
        "pickup_airport_code": {
          "type": "string",
          "description": "IATA code of pickup airport",
          "example": "JFK"
        },
        "pickup_airport": {
          "type": "string",
          "example": "John F. Kennedy International Airport"
        },
        "pickup_seaport": {
          "type": "string",
          "example": "Port of New York"
        },
        "pickup_seaport_code": {
          "type": "string",
          "example": "NYK"
        },
        "pickup_country_code": {
          "type": "string",
          "example": "US"
        },
        "pickup_before_date": {
          "type": "string",
          "format": "date",
          "description": "Latest acceptable pickup date",
          "example": "2024-07-20"
        },
        "pickup_before_time": {
          "type": "string",
          "description": "Latest acceptable pickup time",
          "example": "16:00:00"
        },
        "pickup_ready_date": {
          "type": "string",
          "format": "date",
          "description": "Earliest pickup readiness date",
          "example": "2024-07-15"
        },
        "pickup_ready_time": {
          "type": "string",
          "description": "Earliest pickup readiness time",
          "example": "08:00:00"
        },
        "pickup_hours_from": {
          "type": "string",
          "description": "Pickup window start time",
          "example": "08:00:00"
        },
        "pickup_hours_to": {
          "type": "string",
          "description": "Pickup window end time",
          "example": "17:00:00"
        },
        "pickup_timezone": {
          "type": "string",
          "description": "Timezone for pickup",
          "example": "EST"
        },
        "pickup_cargo_ready": {
          "type": "string",
          "enum": [
            "after",
            "before",
            "between",
            "asap_delivery",
            "unspecified"
          ],
          "example": "after",
          "description": "Type of pickup time for the cargo. E.g. after specified pickup time, before specified pickup time, date range etc."
        },
        "pickup_notes": {
          "type": "string",
          "description": "Notes for pickup loca
  /* truncated */
```

Example:

```json
{
  "quick_request": {
    "title": "Sample Quick Request Title",
    "comments": "Sample Test comments."
  },
  "organizational": {
    "location_ref": "L1234567",
    "cost_center": "CC12345",
    "reason_code": "RC67890",
    "reason_code_group": "RCG112233",
    "custom_field_01": "Custom Value 01",
    "custom_field_02": "Custom Value 02",
    "custom_field_03": "Custom Value 03",
    "custom_long_field_01": "Custom Long Field 01",
    "goods_confirmation_type": "Estimated"
  },
  "schedule": {
    "pickup_address_type": "Commercial",
    "pickup_address_name": "Main Warehouse",
    "pickup_company_name": "Logistics Co.",
    "pickup_city": "New York",
    "pickup_state": "NY",
    "pickup_country": "USA",
    "pickup_airport_code": "JFK",
    "pickup_airport": "John F. Kennedy International Airport",
    "pickup_seaport": "Port of New York",
    "pickup_seaport_code": "NYK",
    "pickup_country_code": "US",
    "pickup_before_date": "2024-07-20",
    "pickup_before_time": "16:00:00",
    "pickup_ready_date": "2024-07-15",
    "pickup_ready_time": "08:00:00",
    "pickup_hours_from": "08:00:00",
    "pickup_hours_to": "17:00:00",
    "pickup_timezone": "EST",
    "pickup_cargo_ready": "After",
    "pickup_notes": "Handle with care",
    "pickup_street_line2": "Building B",
    "delivery_hours_from": "09:00:00",
    "delivery_hours_to": "18:00:00",
    "stop1_address_type": "Residential",
    "stop1_company_name": "Recipient Corp.",
    "stop1_notes": "Leave at front door",
    "stop1_street_line2": "Apt 5B",
    "stop1_street": "1234 Elm St",
    "pickup_street": "5678 Oak St",
    "stop1_country": "USA",
    "stop1_state": "CA",
    "stop1_country_code": "US",
    "stop1_zipcode": "90001",
    "stop1_city": "Los Angeles",
    "stop1_address_name": "Recipient Home",
    "stop1_contact_name": "Jane Doe",
    "stop1_contact_phone": "555-1234",
    "stop1_contact_email": "jane.doe@example.com",
    "stop1_after_date": "2024-07-22",
    "stop1_after_time": "10:00:00",
    "stop1_before_date": "2024-07-23",
    "stop1_before_time": "16:00:00",
    "stop1_timezone": "PST",
    "delivery_cargo_ready": "Before",
    "stop1_airport_code": "LAX",
    "stop1_airport": "Los Angeles International Airport",
    "stop1_seaport_code": "LAX",
    "stop1_seaport": "Port of Los Angeles"
  },
  "packing_list": [
    {
      "handling_unit": "Pallet",
      "handling_unit_value": "1",
      "units": 10,
      "length": 1.2,
      "width": 0.8,
      "height": 1,
      "m_unit": "meters",
      "hazardous": false,
      "container_type": "Standard",
      "temperature_control_required": true,
      "temperature_control_value": "3",
      "temperature_controlled_custom_value": "Store at 5°C",
      "cbm_scope": "Full",
      "l_w_h_cbm_total": 0.96,
      "l_w_h_cbm_piece": 0.096,
      "weight_piece": 50,
      "weight_total": "500.0",
      "w_unit": "kg",
      "stackable": true,
      "is_dangerous_good": false,
      "dangerous_good_value": "",
      "additional_information": "Handle with care",
      "crating_required": true,
      "crating_required_by": "2024-07-20",
      "additional_text": "Ensure packaging integrity",
      "nmfc_class": "Class 70",
      "good_customs_information": [
        {
          "value": 8000,
          "currency_code": "USD",
          "description": "Gear R",
          "hs_code": "E2"
        }
      ],
      "additional_field": "Extra details"
    }
  ],
  "service": {
    "incoterms": null,
    "incoterm_instructions": "",
    "service_level": "",
    "service_type": null,
    "export_clearance": "API_NO_IMPORT_EXPORT_CLEARANCE",
    "export_clearance_instructions": "",
    "transit_clearance": "API_NO_IMPORT_EXPORT_CLEARANCE",
    "transit_clearance_instructions": "",
    "import_clearance": "API_NO_IMPORT_EXPORT_CLEARANCE",
    "import_clearance_instructions": "",
    "insurance": null,
    "insurance_instructions": "",
    "special_requirements": {}
  }
}
```

**Success `200`** — Order successfully created

```json
{
  "type": "object",
  "properties": {
    "success": {
      "type": "boolean",
      "description": "Whether the order was created successfully",
      "example": true
    },
    "order_id": {
      "type": "string",
      "description": "Unique identifier for the created order",
      "example": "ORD-123456"
    }
  }
}
```

Example:

```json
{
  "success": true,
  "order_id": "ORD-123456"
}
```

**Errors**

- `400` — Bad Request – Validation errors or missing fields
- `401` — Unauthorized – Invalid or missing token

#### Tag: System Drafts

#### `GET /api/1/addresses`

- **operationId:** `listAddresses`
- **summary:** List Addresses
- **description:** Discover Address v2 records. Requires `is_new_address_enabled` on the company; returns 403 otherwise. Uses the same availability scoping as draft address resolution. Response is paginated AddressSerializer rows. Use returned `reference_number` and `location_reference_number` on stop writes. ## Request URI ``` GET {ENV_DOMAIN}/api/1/addresses
- **statuses:** 200, 401, 403

**Parameters**

- `Authorization` (header) type=string example=`Token your_token_here` — Replace 'your_token_here' with your token.
- `payment_location` (query) type=string example=`all` — cb_account_number. Use `all` to list addresses across accessible payment locations.

- `query` (query) type=string example=`Singapore` — Search term (matches name, street, location_reference_number, etc.)
- `page` (query) type=integer example=`1` — Page number

**Success `200`** — Paginated list of address objects

```json
{
  "type": "object",
  "properties": {
    "count": {
      "type": "integer",
      "description": "Total number of matching addresses",
      "example": 12
    },
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "reference_number": {
            "type": "string",
            "description": "Unique address reference. Use as stop `address_reference_number`.",
            "example": "A12345678"
          },
          "location_reference_number": {
            "type": "string",
            "description": "ERP location reference. Use as stop `location_reference_number`.",
            "example": "ERP-WH-01"
          },
          "name": {
            "type": "string"
          },
          "street": {
            "type": "string"
          },
          "street_line2": {
            "type": "string"
          },
          "zipcode": {
            "type": "string"
          },
          "city_name": {
            "type": "string"
          },
          "state_name": {
            "type": "string"
          },
          "country_name": {
            "type": "string"
          },
          "contact_name": {
            "type": "string"
          },
          "contact_number": {
            "type": "string"
          },
          "contact_email": {
            "type": "string",
            "format": "email"
          }
        }
      }
    }
  },
  "required": [
    "count",
    "results"
  ]
}
```

Example:

```json
{
  "count": 1,
  "results": [
    {
      "reference_number": "A12345678",
      "location_reference_number": "ERP-WH-01",
      "name": "Warehouse Singapore",
      "street": "30 Example Road",
      "street_line2": null,
      "zipcode": "654321",
      "city_name": "Singapore",
      "state_name": null,
      "country_name": "Singapore",
      "contact_name": "Warehouse Desk",
      "contact_number": "+6511111111",
      "contact_email": "warehouse@example.com"
    }
  ]
}
```

**Errors**

- `401`
- `403`

#### `GET /api/1/requests/draft/`

- **operationId:** `listDrafts`
- **summary:** List view
- **description:** List lightweight summary rows for accessible quote-request drafts (SYSTEM + REGULAR_NEXT_UI). SYSTEM rows use payment-location scope (including location peers). REGULAR_NEXT_UI rows are creator-only. ## Request URI ``` GET {ENV_DOMAIN}/api/1/requests/draft/ Content-Type: application/json
- **statuses:** 200, 401, 403

**Parameters**

- `Authorization` (header) type=string example=`Token your_token_here` — Replace 'your_token_here' with your token.
- `external_id` (query) type=string example=`ERP_ID_1710000000` — Filter — returns drafts matching this external id.

**Success `200`** — Paginated list of draft summaries

```json
{
  "type": "object",
  "properties": {
    "count": {
      "type": "integer",
      "description": "Total number of matching drafts",
      "example": 3
    },
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "draft_reference_number": {
            "type": "string",
            "example": "D12345678"
          },
          "external_id": {
            "type": "string",
            "example": "ERP_ID_1710000000"
          },
          "created": {
            "type": "string",
            "format": "date-time"
          },
          "modified": {
            "type": "string",
            "format": "date-time"
          },
          "title": {
            "type": "string"
          },
          "location": {
            "type": "string",
            "description": "Payment location (`cb_account_number`)"
          },
          "has_validation_errors": {
            "type": "boolean"
          }
        }
      }
    }
  },
  "required": [
    "count",
    "results"
  ]
}
```

Example:

```json
{
  "count": 3,
  "results": [
    {
      "draft_reference_number": "D12345678",
      "external_id": "ERP_ID_1710000000",
      "created": "string",
      "modified": "string",
      "title": "string",
      "location": "string",
      "has_validation_errors": true
    }
  ]
}
```

**Errors**

- `401`
- `403`

#### `POST /api/1/requests/draft/`

- **operationId:** `createDraft`
- **summary:** Create Draft
- **description:** Create a system draft using the canonical v4-style draft payload with `schedule.stops[]`. There is **no minimum cargo/schedule payload** beyond a valid JSON object and auth headers — the more you send, the less UI cleanup is needed before convert. `{}` is not typical; send at least `external_id` plus the objects you know. `invited_providers.providers` accepts ids, provider references, names, or slugs. The stored/returned document uses **canonical provider
- **statuses:** 201, 400, 401, 403

**Parameters**

- `Content-Type` (header) type=string example=`application/json`
- `Authorization` (header) type=string example=`Token your_token_here` — Replace 'your_token_here' with your token.

**Request body** (required; application/json)

Schema (resolved summary):

```json
{
  "type": "object",
  "properties": {
    "external_id": {
      "type": "string",
      "description": "External ERP identifier for this draft (e.g. `ERP_ID_{timestamp}`)",
      "example": "ERP_ID_1710000000"
    },
    "shipment": {
      "type": "object",
      "properties": {
        "title": {
          "type": "string",
          "example": "SG warehouse to NL DC"
        },
        "quoting_deadline_date": {
          "type": "string",
          "format": "date",
          "description": "Quote deadline date"
        },
        "quoting_deadline_time": {
          "type": "string",
          "format": "time",
          "description": "Quote deadline time of day"
        },
        "confirmation_date": {
          "type": "string",
          "format": "date"
        },
        "confirmation_time": {
          "type": "string",
          "format": "time"
        },
        "comments": {
          "type": "string"
        }
      },
      "description": "Shipment-level title, timers, and comments"
    },
    "organizational": {
      "type": "object",
      "properties": {
        "location": {
          "type": "string",
          "description": "`cb_account_number` of the payment location",
          "example": "SL2963758"
        },
        "invoice_location": {
          "type": "string",
          "description": "Organizational unit that should receive provider invoices"
        },
        "reason_code_group": {
          "type": "string"
        },
        "reason_code": {
          "type": "string"
        },
        "custom_field_01": {
          "type": "string"
        },
        "custom_field_02": {
          "type": "string"
        },
        "custom_field_03": {
          "type": "string"
        },
        "custom_long_field_01": {
          "type": "string"
        },
        "cost_center": {
          "type": "string"
        },
        "goods_confirmation_type": {
          "type": "string",
          "enum": [
            "Estimated",
            "Finalized"
          ],
          "example": "Estimated",
          "description": "Packing-list confirmation status"
        },
        "cost_recovery_required": {
          "type": "boolean"
        },
        "custom_cost_recovery_field1": {
          "type": "string"
        },
        "custom_cost_recovery_field2": {
          "type": "string"
        }
      },
      "description": "Organizational / accounting fields for the draft"
    },
    "schedule": {
      "type": "object",
      "properties": {
        "multistop_instructions": {
          "type": "string"
        },
        "stops": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "consignee": {
          "type": "string"
        },
        "notify_party": {
          "type": "string"
        },
        "pickup_address_type": {
          "type": "string",
          "enum": [
            "address",
            "airport",
            "seaport"
          ],
          "description": "Classic string address type. Used on classic pickup/delivery fields\nand on consignee / notify party — **not** on `stops[]`.\n"
        },
        "stop1_address_type": {
          "type": "string",
          "enum": [
            "address",
            "airport",
            "seaport"
          ],
          "description": "Classic string address type. Used on classic pickup/delivery fields\nand on consignee / notify party — **not** on `stops[]`.\n"
        },
        "pickup_cargo_ready": {
          "type": "string",
          "enum": [
            "after",
            "between",
            "asap_delivery",
            "unspecified"
          ],
          "description": "Classic pickup cargo-ready window. **Not** used on `stops[]`."
        },
        "delivery_cargo_ready": {
          "type": "string",
          "enum": [
            "before",
            "between",
            "asap_delivery",
            "unspecified"
          ],
          "description": "Classic delivery cargo-ready window. **Not** used on `stops[]`."
        }
      },
      "description": "Routing. Canonical writes use `stops[]` (integer enums).\n\nOptional classic fields (`pickup_address_type`, `pickup_cargo_ready`,\n`delivery_cargo_ready`, `stop1_address_type`) use **string** enums and\na"
    },
    "packing_list": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "line_key": {
            "type": "string",
            "description": "Caller or server line identifier"
          },
          "pickup_stop_key": {
            "type": "string",
            "description": "`stop_key` of the pickup stop for this line. Cleared to null if that stop is deleted.",
            "example": "pickup-1"
          },
          "delivery_stop_key": {
            "type": "string",
            "description": "`stop_key` of the delivery stop for this line. Cleared to null if that stop is deleted.",
            "example": "delivery-1"
          },
          "good_item_id": {
            "type": "integer"
          },
          "handling_unit": {
            "type": "string",
            "description": "Handling unit type. Standard values:\n\n`bag`, `box`, `carton`, `case`, `crate`, `container`, `pallet`, `tube`\n\nCompany-configured custom units are also accepted.\n",
            "example": "pallet"
          },
          "handling_unit_value": {
            "type": "string",
            "description": "For `handling_unit=container`, use `LCL` or `FCL`.\nOtherwise free text or `null`.\n",
            "example": "FCL"
          },
          "units": {
            "type": "integer",
            "description": "Quantity of this handling unit",
            "example": 2
          },
          "length": {
            "type": "number"
          },
          "width": {
            "type": "number"
          },
          "height": {
            "type": "number"
          },
          "m_unit": {
            "type": "st
  /* truncated */
```

Example:

```json
{
  "external_id": "ERP_ID_1710000000"
}
```

**Success `201`** — Full draft document

```json
{
  "type": "object",
  "properties": {
    "draft_reference_number": {
      "type": "string",
      "description": "Server-assigned draft reference number",
      "example": "D12345678"
    },
    "created": {
      "type": "string",
      "format": "date-time"
    },
    "modified": {
      "type": "string",
      "format": "date-time"
    },
    "has_validation_errors": {
      "type": "boolean"
    },
    "external_id": {
      "type": "string"
    },
    "shipment": {
      "type": "object",
      "properties": {
        "title": {
          "type": "string",
          "example": "SG warehouse to NL DC"
        },
        "quoting_deadline_date": {
          "type": "string",
          "format": "date",
          "description": "Quote deadline date"
        },
        "quoting_deadline_time": {
          "type": "string",
          "format": "time",
          "description": "Quote deadline time of day"
        },
        "confirmation_date": {
          "type": "string",
          "format": "date"
        },
        "confirmation_time": {
          "type": "string",
          "format": "time"
        },
        "comments": {
          "type": "string"
        }
      },
      "description": "Shipment-level title, timers, and comments"
    },
    "organizational": {
      "type": "object",
      "properties": {
        "location": {
          "type": "string",
          "description": "`cb_account_number` of the payment location",
          "example": "SL2963758"
        },
        "invoice_location": {
          "type": "string",
          "description": "Organizational unit that should receive provider invoices"
        },
        "reason_code_group": {
          "type": "string"
        },
        "reason_code": {
          "type": "string"
        },
        "custom_field_01": {
          "type": "string"
        },
        "custom_field_02": {
          "type": "string"
        },
        "custom_field_03": {
          "type": "string"
        },
        "custom_long_field_01": {
          "type": "string"
        },
        "cost_center": {
          "type": "string"
        },
        "goods_confirmation_type": {
          "type": "string",
          "enum": [
            "Estimated",
            "Finalized"
          ],
          "example": "Estimated",
          "description": "Packing-list confirmation status"
        },
        "cost_recovery_required": {
          "type": "boolean"
        },
        "custom_cost_recovery_field1": {
          "type": "string"
        },
        "custom_cost_recovery_field2": {
          "type": "string"
        }
      },
      "description": "Organizational / accounting fields for the draft"
    },
    "schedule": {
      "type": "string"
    },
    "packing_list": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "line_key": {
            "type": "string",
            "description": "Caller or server line identifier"
          },
          "pickup_stop_key": {
            "type": "string",
            "description": "`stop_key` of the pickup stop for this line. Cleared to null if that stop is deleted.",
            "example": "pickup-1"
          },
          "delivery_stop_key": {
            "type": "string",
            "description": "`stop_key` of the delivery stop for this line. Cleared to null if that stop is deleted.",
            "example": "delivery-1"
          },
          "good_item_id": {
            "type": "integer"
          },
          "handling_unit": {
            "type": "string",
            "description": "Handling unit type. Standard values:\n\n`bag`, `box`, `carton`, `case`, `crate`, `container`, `pallet`, `tube`\n\nCompany-configured custom units are also accepted.\n",
            "example": "pallet"
          },
          "handling_unit_value": {
            "type": "string",
            "description": "For `handling_unit=container`, use `LCL` or `FCL`.\nOtherwise free text or `null`.\n",
            "example": "FCL"
          },
          "units": {
            "type": "integer",
            "description": "Quantity of this handling unit",
            "example": 2
          },
          "length": {
            "type": "number"
          },
          "width": {
            "type": "number"
          },
          "height": {
            "type": "number"
          },
          "m_unit": {
            "type": "string",
            "enum": [
              "cm",
              "inch"
            ],
            "example": "cm",
            "description": "Length/width/height unit"
          },
          "weight_piece": {
            "type": "number",
            "description": "Weight of one piece. Some flows also accept `total_kg` / `total_lbs`."
          },
          "w_unit": {
            "type": "string",
            "enum": [
              "kg",
              "lbs",
              "total_kg",
              "total_lbs"
            ],
            "example": "kg",
            "description": "Weight unit. Typical values: `kg`, `lbs`.\nSome flows use `total_kg` / `total_lbs`.\n"
          },
          "cbm_scope": {
            "type": "string",
            "enum": [
              "piece",
              "total"
            ],
            "example": "piece",
            "description": "Whether cubic measurements apply per piece or as a total"
          },
          "container_type": {
            "type": "string",
            "enum": [
              "1",
              "2",
              "3",
              "4",
              "5",
              "6",
              "7",
              "8",
              "9",
              "10",
              "11",
              "12",
              "13",
              "14",
              "15",
              "16",
              "17",
              "20",
              "21",
              "22",
              "23",
              "24",
              "25",
              "26"
            ],
            "example": "12",
            "description
  /* truncated */
```

Example:

```json
{
  "draft_reference_number": "D12345678",
  "created": "string",
  "modified": "string",
  "has_validation_errors": true,
  "external_id": "string",
  "shipment": {
    "title": "SG warehouse to NL DC",
    "quoting_deadline_date": "string",
    "quoting_deadline_time": "string",
    "confirmation_date": "string",
    "confirmation_time": "string",
    "comments": "string"
  },
  "organizational": {
    "location": "SL2963758",
    "invoice_location": "string",
    "reason_code_group": "string",
    "reason_code": "string",
    "custom_field_01": "string",
    "custom_field_02": "string",
    "custom_field_03": "string",
    "custom_long_field_01": "string",
    "cost_center": "string",
    "goods_confirmation_type": "Estimated",
    "cost_recovery_required": true,
    "custom_cost_recovery_field1": "string",
    "custom_cost_recovery_field2": "string"
  },
  "packing_list": [
    {
      "line_key": "string",
      "pickup_stop_key": "pickup-1",
      "delivery_stop_key": "delivery-1",
      "good_item_id": 0,
      "handling_unit": "pallet",
      "handling_unit_value": "FCL",
      "units": 2,
      "length": 0,
      "width": 0,
      "height": 0,
      "m_unit": "cm",
      "weight_piece": 0,
      "w_unit": "kg",
      "cbm_scope": "piece",
      "container_type": "12",
      "temperature_control_required": true,
      "temperature_control_value": "1",
      "temperature_controlled_custom_value": "string",
      "is_dangerous_good": true,
      "dangerous_good_value": "1",
      "nmfc_class": "70",
      "hazardous": true,
      "stackable": true,
      "handling_required": true,
      "crating_required": true,
      "additional_information": "string",
      "good_customs_information": [
        {
          "value": 8000,
          "currency_code": "USD",
          "description": "Spare parts",
          "hs_code": "8483.40"
        }
      ]
    }
  ],
  "service": {
    "incoterms": "DAP",
    "incoterm_instructions": "string",
    "service_type": "DTD",
    "service_level": "5",
    "export_clearance": "no",
    "transit_clearance": "no",
    "import_clearance": "no",
    "export_clearance_instructions": "string",
    "transit_clearance_instructions": "string",
    "import_clearance_instructions": "string",
    "insurance": true,
    "insurance_instructions": "string",
    "special_requirements": {}
  },
  "invited_modes": {
    "OBC": true,
    "air_charter": true,
    "NFO": true,
    "regular_air": true,
    "road_freight": true,
    "ocean_freight": true,
    "parcel": true,
    "rail_freight": true,
    "road_freight_option": "ftl",
    "custom": [
      {}
    ]
  },
  "invited_providers": {
    "providers": [
      "string"
    ],
    "parcel_accounts": [
      "string"
    ]
  },
  "bucket_attachments": [
    {
      "id": 0,
      "file": "FU84121391",
      "filename": "certificate.pdf",
      "url": "string",
      "bucket_name": "CERTIFICATE_OF_ORIGIN"
    }
  ],
  "other_attachments": [
    {
      "id": 0,
      "name": "extra.pdf",
      "reference_number": "FU12345678",
      "file_extension": "pdf",
      "url": "string"
    }
  ]
}
```

**Errors**

- `400`
- `401`
- `403`

#### `GET /api/1/requests/draft/{draft_id}/`

- **operationId:** `getDraftDetail`
- **summary:** Draft Detail
- **description:** Fetch the full v4-style draft document for an accessible quote-request draft (SYSTEM or REGULAR_NEXT_UI per access policy). Returns the stored payload including canonical `schedule.stops[]` (no `address_id`), `packing_list[]`, `other_attachments` (from the upload endpoint), `bucket_attachments` when present, and `invited_providers` as provider references. ## Request URI ```
- **statuses:** 200, 401, 403, 404

**Parameters**

- `Authorization` (header) type=string example=`Token your_token_here` — Replace 'your_token_here' with your token.
- `draft_id` (path, required) type=string pattern=`^SD[-\d]+$` example=`SD12345678` — Draft reference number returned on create. Pattern: `SD` followed by digits (e.g. `SD12345678`).

**Success `200`** — Full draft document

```json
{
  "type": "object",
  "properties": {
    "draft_reference_number": {
      "type": "string",
      "description": "Server-assigned draft reference number",
      "example": "D12345678"
    },
    "created": {
      "type": "string",
      "format": "date-time"
    },
    "modified": {
      "type": "string",
      "format": "date-time"
    },
    "has_validation_errors": {
      "type": "boolean"
    },
    "external_id": {
      "type": "string"
    },
    "shipment": {
      "type": "object",
      "properties": {
        "title": {
          "type": "string",
          "example": "SG warehouse to NL DC"
        },
        "quoting_deadline_date": {
          "type": "string",
          "format": "date",
          "description": "Quote deadline date"
        },
        "quoting_deadline_time": {
          "type": "string",
          "format": "time",
          "description": "Quote deadline time of day"
        },
        "confirmation_date": {
          "type": "string",
          "format": "date"
        },
        "confirmation_time": {
          "type": "string",
          "format": "time"
        },
        "comments": {
          "type": "string"
        }
      },
      "description": "Shipment-level title, timers, and comments"
    },
    "organizational": {
      "type": "object",
      "properties": {
        "location": {
          "type": "string",
          "description": "`cb_account_number` of the payment location",
          "example": "SL2963758"
        },
        "invoice_location": {
          "type": "string",
          "description": "Organizational unit that should receive provider invoices"
        },
        "reason_code_group": {
          "type": "string"
        },
        "reason_code": {
          "type": "string"
        },
        "custom_field_01": {
          "type": "string"
        },
        "custom_field_02": {
          "type": "string"
        },
        "custom_field_03": {
          "type": "string"
        },
        "custom_long_field_01": {
          "type": "string"
        },
        "cost_center": {
          "type": "string"
        },
        "goods_confirmation_type": {
          "type": "string",
          "enum": [
            "Estimated",
            "Finalized"
          ],
          "example": "Estimated",
          "description": "Packing-list confirmation status"
        },
        "cost_recovery_required": {
          "type": "boolean"
        },
        "custom_cost_recovery_field1": {
          "type": "string"
        },
        "custom_cost_recovery_field2": {
          "type": "string"
        }
      },
      "description": "Organizational / accounting fields for the draft"
    },
    "schedule": {
      "type": "string"
    },
    "packing_list": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "line_key": {
            "type": "string",
            "description": "Caller or server line identifier"
          },
          "pickup_stop_key": {
            "type": "string",
            "description": "`stop_key` of the pickup stop for this line. Cleared to null if that stop is deleted.",
            "example": "pickup-1"
          },
          "delivery_stop_key": {
            "type": "string",
            "description": "`stop_key` of the delivery stop for this line. Cleared to null if that stop is deleted.",
            "example": "delivery-1"
          },
          "good_item_id": {
            "type": "integer"
          },
          "handling_unit": {
            "type": "string",
            "description": "Handling unit type. Standard values:\n\n`bag`, `box`, `carton`, `case`, `crate`, `container`, `pallet`, `tube`\n\nCompany-configured custom units are also accepted.\n",
            "example": "pallet"
          },
          "handling_unit_value": {
            "type": "string",
            "description": "For `handling_unit=container`, use `LCL` or `FCL`.\nOtherwise free text or `null`.\n",
            "example": "FCL"
          },
          "units": {
            "type": "integer",
            "description": "Quantity of this handling unit",
            "example": 2
          },
          "length": {
            "type": "number"
          },
          "width": {
            "type": "number"
          },
          "height": {
            "type": "number"
          },
          "m_unit": {
            "type": "string",
            "enum": [
              "cm",
              "inch"
            ],
            "example": "cm",
            "description": "Length/width/height unit"
          },
          "weight_piece": {
            "type": "number",
            "description": "Weight of one piece. Some flows also accept `total_kg` / `total_lbs`."
          },
          "w_unit": {
            "type": "string",
            "enum": [
              "kg",
              "lbs",
              "total_kg",
              "total_lbs"
            ],
            "example": "kg",
            "description": "Weight unit. Typical values: `kg`, `lbs`.\nSome flows use `total_kg` / `total_lbs`.\n"
          },
          "cbm_scope": {
            "type": "string",
            "enum": [
              "piece",
              "total"
            ],
            "example": "piece",
            "description": "Whether cubic measurements apply per piece or as a total"
          },
          "container_type": {
            "type": "string",
            "enum": [
              "1",
              "2",
              "3",
              "4",
              "5",
              "6",
              "7",
              "8",
              "9",
              "10",
              "11",
              "12",
              "13",
              "14",
              "15",
              "16",
              "17",
              "20",
              "21",
              "22",
              "23",
              "24",
              "25",
              "26"
            ],
            "example": "12",
            "description
  /* truncated */
```

Example:

```json
{
  "draft_reference_number": "D12345678",
  "created": "string",
  "modified": "string",
  "has_validation_errors": true,
  "external_id": "string",
  "shipment": {
    "title": "SG warehouse to NL DC",
    "quoting_deadline_date": "string",
    "quoting_deadline_time": "string",
    "confirmation_date": "string",
    "confirmation_time": "string",
    "comments": "string"
  },
  "organizational": {
    "location": "SL2963758",
    "invoice_location": "string",
    "reason_code_group": "string",
    "reason_code": "string",
    "custom_field_01": "string",
    "custom_field_02": "string",
    "custom_field_03": "string",
    "custom_long_field_01": "string",
    "cost_center": "string",
    "goods_confirmation_type": "Estimated",
    "cost_recovery_required": true,
    "custom_cost_recovery_field1": "string",
    "custom_cost_recovery_field2": "string"
  },
  "packing_list": [
    {
      "line_key": "string",
      "pickup_stop_key": "pickup-1",
      "delivery_stop_key": "delivery-1",
      "good_item_id": 0,
      "handling_unit": "pallet",
      "handling_unit_value": "FCL",
      "units": 2,
      "length": 0,
      "width": 0,
      "height": 0,
      "m_unit": "cm",
      "weight_piece": 0,
      "w_unit": "kg",
      "cbm_scope": "piece",
      "container_type": "12",
      "temperature_control_required": true,
      "temperature_control_value": "1",
      "temperature_controlled_custom_value": "string",
      "is_dangerous_good": true,
      "dangerous_good_value": "1",
      "nmfc_class": "70",
      "hazardous": true,
      "stackable": true,
      "handling_required": true,
      "crating_required": true,
      "additional_information": "string",
      "good_customs_information": [
        {
          "value": 8000,
          "currency_code": "USD",
          "description": "Spare parts",
          "hs_code": "8483.40"
        }
      ]
    }
  ],
  "service": {
    "incoterms": "DAP",
    "incoterm_instructions": "string",
    "service_type": "DTD",
    "service_level": "5",
    "export_clearance": "no",
    "transit_clearance": "no",
    "import_clearance": "no",
    "export_clearance_instructions": "string",
    "transit_clearance_instructions": "string",
    "import_clearance_instructions": "string",
    "insurance": true,
    "insurance_instructions": "string",
    "special_requirements": {}
  },
  "invited_modes": {
    "OBC": true,
    "air_charter": true,
    "NFO": true,
    "regular_air": true,
    "road_freight": true,
    "ocean_freight": true,
    "parcel": true,
    "rail_freight": true,
    "road_freight_option": "ftl",
    "custom": [
      {}
    ]
  },
  "invited_providers": {
    "providers": [
      "string"
    ],
    "parcel_accounts": [
      "string"
    ]
  },
  "bucket_attachments": [
    {
      "id": 0,
      "file": "FU84121391",
      "filename": "certificate.pdf",
      "url": "string",
      "bucket_name": "CERTIFICATE_OF_ORIGIN"
    }
  ],
  "other_attachments": [
    {
      "id": 0,
      "name": "extra.pdf",
      "reference_number": "FU12345678",
      "file_extension": "pdf",
      "url": "string"
    }
  ]
}
```

**Errors**

- `401`
- `403`
- `404`

#### `PATCH /api/1/requests/draft/{draft_id}/`

- **operationId:** `patchDraft`
- **summary:** Update Draft
- **description:** Partial update of the whole draft document. Deep-merges this payload into the existing draft, then persists canonical `schedule.stops[]`. Returns 200 with the full updated document on success. **Attachments:** do **not** send `other_attachments` or `bucket_attachments` on PATCH. Upload other-files with `POST /api/1/requests/draft/{draft_id}/attachments/`. ## Request URI ``` PATCH {ENV_DOMAIN}/api/1/requests/draft/{draft_id}/
- **statuses:** 200, 400, 401, 403, 404

**Parameters**

- `Content-Type` (header) type=string example=`application/json`
- `Authorization` (header) type=string example=`Token your_token_here` — Replace 'your_token_here' with your token.
- `draft_id` (path, required) type=string pattern=`^SD[-\d]+$` example=`SD12345678` — Draft reference number returned on create. Pattern: `SD` followed by digits (e.g. `SD12345678`).

**Request body** (required; application/json)

Schema (resolved summary):

```json
{
  "type": "object",
  "properties": {
    "external_id": {
      "type": "string"
    },
    "shipment": {
      "type": "object",
      "properties": {
        "title": {
          "type": "string",
          "example": "SG warehouse to NL DC"
        },
        "quoting_deadline_date": {
          "type": "string",
          "format": "date",
          "description": "Quote deadline date"
        },
        "quoting_deadline_time": {
          "type": "string",
          "format": "time",
          "description": "Quote deadline time of day"
        },
        "confirmation_date": {
          "type": "string",
          "format": "date"
        },
        "confirmation_time": {
          "type": "string",
          "format": "time"
        },
        "comments": {
          "type": "string"
        }
      },
      "description": "Shipment-level title, timers, and comments"
    },
    "organizational": {
      "type": "object",
      "properties": {
        "location": {
          "type": "string",
          "description": "`cb_account_number` of the payment location",
          "example": "SL2963758"
        },
        "invoice_location": {
          "type": "string",
          "description": "Organizational unit that should receive provider invoices"
        },
        "reason_code_group": {
          "type": "string"
        },
        "reason_code": {
          "type": "string"
        },
        "custom_field_01": {
          "type": "string"
        },
        "custom_field_02": {
          "type": "string"
        },
        "custom_field_03": {
          "type": "string"
        },
        "custom_long_field_01": {
          "type": "string"
        },
        "cost_center": {
          "type": "string"
        },
        "goods_confirmation_type": {
          "type": "string",
          "enum": [
            "Estimated",
            "Finalized"
          ],
          "example": "Estimated",
          "description": "Packing-list confirmation status"
        },
        "cost_recovery_required": {
          "type": "boolean"
        },
        "custom_cost_recovery_field1": {
          "type": "string"
        },
        "custom_cost_recovery_field2": {
          "type": "string"
        }
      },
      "description": "Organizational / accounting fields for the draft"
    },
    "schedule": {
      "type": "object",
      "properties": {
        "multistop_instructions": {
          "type": "string"
        },
        "stops": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "consignee": {
          "type": "string"
        },
        "notify_party": {
          "type": "string"
        },
        "pickup_address_type": {
          "type": "string",
          "enum": [
            "address",
            "airport",
            "seaport"
          ],
          "description": "Classic string address type. Used on classic pickup/delivery fields\nand on consignee / notify party — **not** on `stops[]`.\n"
        },
        "stop1_address_type": {
          "type": "string",
          "enum": [
            "address",
            "airport",
            "seaport"
          ],
          "description": "Classic string address type. Used on classic pickup/delivery fields\nand on consignee / notify party — **not** on `stops[]`.\n"
        },
        "pickup_cargo_ready": {
          "type": "string",
          "enum": [
            "after",
            "between",
            "asap_delivery",
            "unspecified"
          ],
          "description": "Classic pickup cargo-ready window. **Not** used on `stops[]`."
        },
        "delivery_cargo_ready": {
          "type": "string",
          "enum": [
            "before",
            "between",
            "asap_delivery",
            "unspecified"
          ],
          "description": "Classic delivery cargo-ready window. **Not** used on `stops[]`."
        }
      },
      "description": "Routing. Canonical writes use `stops[]` (integer enums).\n\nOptional classic fields (`pickup_address_type`, `pickup_cargo_ready`,\n`delivery_cargo_ready`, `stop1_address_type`) use **string** enums and\na"
    },
    "packing_list": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "line_key": {
            "type": "string",
            "description": "Caller or server line identifier"
          },
          "pickup_stop_key": {
            "type": "string",
            "description": "`stop_key` of the pickup stop for this line. Cleared to null if that stop is deleted.",
            "example": "pickup-1"
          },
          "delivery_stop_key": {
            "type": "string",
            "description": "`stop_key` of the delivery stop for this line. Cleared to null if that stop is deleted.",
            "example": "delivery-1"
          },
          "good_item_id": {
            "type": "integer"
          },
          "handling_unit": {
            "type": "string",
            "description": "Handling unit type. Standard values:\n\n`bag`, `box`, `carton`, `case`, `crate`, `container`, `pallet`, `tube`\n\nCompany-configured custom units are also accepted.\n",
            "example": "pallet"
          },
          "handling_unit_value": {
            "type": "string",
            "description": "For `handling_unit=container`, use `LCL` or `FCL`.\nOtherwise free text or `null`.\n",
            "example": "FCL"
          },
          "units": {
            "type": "integer",
            "description": "Quantity of this handling unit",
            "example": 2
          },
          "length": {
            "type": "number"
          },
          "width": {
            "type": "number"
          },
          "height": {
            "type": "number"
          },
          "m_unit": {
            "type": "string",
            "enum": [
              "cm",
              "inch"
            ],
            "example": "cm",
            "de
  /* truncated */
```

Example:

```json
{
  "shipment": {
    "title": "Updated title",
    "comments": "Updated via PATCH"
  },
  "organizational": {
    "cost_center": "Updated cost center",
    "invoice_location": null
  },
  "service": {
    "service_type": "DTD",
    "incoterms": "DAP",
    "incoterm_instructions": "Delivered at place",
    "insurance": true,
    "insurance_instructions": "Full value coverage"
  },
  "invited_modes": {
    "OBC": true,
    "NFO": true,
    "air_charter": false
  }
}
```

**Success `200`** — Full updated draft document

```json
{
  "type": "object",
  "properties": {
    "draft_reference_number": {
      "type": "string",
      "description": "Server-assigned draft reference number",
      "example": "D12345678"
    },
    "created": {
      "type": "string",
      "format": "date-time"
    },
    "modified": {
      "type": "string",
      "format": "date-time"
    },
    "has_validation_errors": {
      "type": "boolean"
    },
    "external_id": {
      "type": "string"
    },
    "shipment": {
      "type": "object",
      "properties": {
        "title": {
          "type": "string",
          "example": "SG warehouse to NL DC"
        },
        "quoting_deadline_date": {
          "type": "string",
          "format": "date",
          "description": "Quote deadline date"
        },
        "quoting_deadline_time": {
          "type": "string",
          "format": "time",
          "description": "Quote deadline time of day"
        },
        "confirmation_date": {
          "type": "string",
          "format": "date"
        },
        "confirmation_time": {
          "type": "string",
          "format": "time"
        },
        "comments": {
          "type": "string"
        }
      },
      "description": "Shipment-level title, timers, and comments"
    },
    "organizational": {
      "type": "object",
      "properties": {
        "location": {
          "type": "string",
          "description": "`cb_account_number` of the payment location",
          "example": "SL2963758"
        },
        "invoice_location": {
          "type": "string",
          "description": "Organizational unit that should receive provider invoices"
        },
        "reason_code_group": {
          "type": "string"
        },
        "reason_code": {
          "type": "string"
        },
        "custom_field_01": {
          "type": "string"
        },
        "custom_field_02": {
          "type": "string"
        },
        "custom_field_03": {
          "type": "string"
        },
        "custom_long_field_01": {
          "type": "string"
        },
        "cost_center": {
          "type": "string"
        },
        "goods_confirmation_type": {
          "type": "string",
          "enum": [
            "Estimated",
            "Finalized"
          ],
          "example": "Estimated",
          "description": "Packing-list confirmation status"
        },
        "cost_recovery_required": {
          "type": "boolean"
        },
        "custom_cost_recovery_field1": {
          "type": "string"
        },
        "custom_cost_recovery_field2": {
          "type": "string"
        }
      },
      "description": "Organizational / accounting fields for the draft"
    },
    "schedule": {
      "type": "string"
    },
    "packing_list": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "line_key": {
            "type": "string",
            "description": "Caller or server line identifier"
          },
          "pickup_stop_key": {
            "type": "string",
            "description": "`stop_key` of the pickup stop for this line. Cleared to null if that stop is deleted.",
            "example": "pickup-1"
          },
          "delivery_stop_key": {
            "type": "string",
            "description": "`stop_key` of the delivery stop for this line. Cleared to null if that stop is deleted.",
            "example": "delivery-1"
          },
          "good_item_id": {
            "type": "integer"
          },
          "handling_unit": {
            "type": "string",
            "description": "Handling unit type. Standard values:\n\n`bag`, `box`, `carton`, `case`, `crate`, `container`, `pallet`, `tube`\n\nCompany-configured custom units are also accepted.\n",
            "example": "pallet"
          },
          "handling_unit_value": {
            "type": "string",
            "description": "For `handling_unit=container`, use `LCL` or `FCL`.\nOtherwise free text or `null`.\n",
            "example": "FCL"
          },
          "units": {
            "type": "integer",
            "description": "Quantity of this handling unit",
            "example": 2
          },
          "length": {
            "type": "number"
          },
          "width": {
            "type": "number"
          },
          "height": {
            "type": "number"
          },
          "m_unit": {
            "type": "string",
            "enum": [
              "cm",
              "inch"
            ],
            "example": "cm",
            "description": "Length/width/height unit"
          },
          "weight_piece": {
            "type": "number",
            "description": "Weight of one piece. Some flows also accept `total_kg` / `total_lbs`."
          },
          "w_unit": {
            "type": "string",
            "enum": [
              "kg",
              "lbs",
              "total_kg",
              "total_lbs"
            ],
            "example": "kg",
            "description": "Weight unit. Typical values: `kg`, `lbs`.\nSome flows use `total_kg` / `total_lbs`.\n"
          },
          "cbm_scope": {
            "type": "string",
            "enum": [
              "piece",
              "total"
            ],
            "example": "piece",
            "description": "Whether cubic measurements apply per piece or as a total"
          },
          "container_type": {
            "type": "string",
            "enum": [
              "1",
              "2",
              "3",
              "4",
              "5",
              "6",
              "7",
              "8",
              "9",
              "10",
              "11",
              "12",
              "13",
              "14",
              "15",
              "16",
              "17",
              "20",
              "21",
              "22",
              "23",
              "24",
              "25",
              "26"
            ],
            "example": "12",
            "description
  /* truncated */
```

Example:

```json
{
  "draft_reference_number": "D12345678",
  "created": "string",
  "modified": "string",
  "has_validation_errors": true,
  "external_id": "string",
  "shipment": {
    "title": "SG warehouse to NL DC",
    "quoting_deadline_date": "string",
    "quoting_deadline_time": "string",
    "confirmation_date": "string",
    "confirmation_time": "string",
    "comments": "string"
  },
  "organizational": {
    "location": "SL2963758",
    "invoice_location": "string",
    "reason_code_group": "string",
    "reason_code": "string",
    "custom_field_01": "string",
    "custom_field_02": "string",
    "custom_field_03": "string",
    "custom_long_field_01": "string",
    "cost_center": "string",
    "goods_confirmation_type": "Estimated",
    "cost_recovery_required": true,
    "custom_cost_recovery_field1": "string",
    "custom_cost_recovery_field2": "string"
  },
  "packing_list": [
    {
      "line_key": "string",
      "pickup_stop_key": "pickup-1",
      "delivery_stop_key": "delivery-1",
      "good_item_id": 0,
      "handling_unit": "pallet",
      "handling_unit_value": "FCL",
      "units": 2,
      "length": 0,
      "width": 0,
      "height": 0,
      "m_unit": "cm",
      "weight_piece": 0,
      "w_unit": "kg",
      "cbm_scope": "piece",
      "container_type": "12",
      "temperature_control_required": true,
      "temperature_control_value": "1",
      "temperature_controlled_custom_value": "string",
      "is_dangerous_good": true,
      "dangerous_good_value": "1",
      "nmfc_class": "70",
      "hazardous": true,
      "stackable": true,
      "handling_required": true,
      "crating_required": true,
      "additional_information": "string",
      "good_customs_information": [
        {
          "value": 8000,
          "currency_code": "USD",
          "description": "Spare parts",
          "hs_code": "8483.40"
        }
      ]
    }
  ],
  "service": {
    "incoterms": "DAP",
    "incoterm_instructions": "string",
    "service_type": "DTD",
    "service_level": "5",
    "export_clearance": "no",
    "transit_clearance": "no",
    "import_clearance": "no",
    "export_clearance_instructions": "string",
    "transit_clearance_instructions": "string",
    "import_clearance_instructions": "string",
    "insurance": true,
    "insurance_instructions": "string",
    "special_requirements": {}
  },
  "invited_modes": {
    "OBC": true,
    "air_charter": true,
    "NFO": true,
    "regular_air": true,
    "road_freight": true,
    "ocean_freight": true,
    "parcel": true,
    "rail_freight": true,
    "road_freight_option": "ftl",
    "custom": [
      {}
    ]
  },
  "invited_providers": {
    "providers": [
      "string"
    ],
    "parcel_accounts": [
      "string"
    ]
  },
  "bucket_attachments": [
    {
      "id": 0,
      "file": "FU84121391",
      "filename": "certificate.pdf",
      "url": "string",
      "bucket_name": "CERTIFICATE_OF_ORIGIN"
    }
  ],
  "other_attachments": [
    {
      "id": 0,
      "name": "extra.pdf",
      "reference_number": "FU12345678",
      "file_extension": "pdf",
      "url": "string"
    }
  ]
}
```

**Errors**

- `400`
- `401`
- `403`
- `404`

#### `POST /api/1/requests/draft/{draft_id}/attachments/`

- **operationId:** `uploadDraftAttachment`
- **summary:** Upload Draft Attachment
- **description:** Multipart upload onto an existing system draft. Creates a FileUpload linked to the draft and **appends** an entry to `other_attachments`. This is the supported way to add new other-files after create. Uses the same file-type validation as common file upload, and the `common_file_upload` throttle scope. ## Request URI ``` POST {ENV_DOMAIN}/api/1/requests/draft/{draft_id}/attachments/
- **statuses:** 201, 400, 401, 403, 404

**Parameters**

- `Authorization` (header) type=string example=`Token your_token_here` — Replace 'your_token_here' with your token.
- `draft_id` (path, required) type=string pattern=`^SD[-\d]+$` example=`SD12345678` — Draft reference number returned on create. Pattern: `SD` followed by digits (e.g. `SD12345678`).

**Request body** (required; multipart/form-data)

Schema (resolved summary):

```json
{
  "type": "object",
  "properties": {
    "file": {
      "type": "string",
      "format": "binary",
      "description": "File to upload (same type rules as common file upload)."
    },
    "filename": {
      "type": "string",
      "description": "Optional display name override.",
      "example": "extra.pdf"
    }
  },
  "required": [
    "file"
  ]
}
```

Example:

```json
{
  "filename": "packing-list.pdf"
}
```

**Success `201`** — Upload receipt

```json
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "example": "extra.pdf"
    },
    "reference_number": {
      "type": "string",
      "example": "FU12345678"
    },
    "file_extension": {
      "type": "string",
      "example": "pdf"
    }
  },
  "required": [
    "name",
    "reference_number",
    "file_extension"
  ]
}
```

Example:

```json
{
  "name": "extra.pdf",
  "reference_number": "FU12345678",
  "file_extension": "pdf"
}
```

**Errors**

- `400`
- `401`
- `403`
- `404`

#### `POST /api/1/requests/draft/{draft_id}/stops/`

- **operationId:** `addStop`
- **summary:** Add Stop
- **description:** Append a single stop to `schedule.stops[]`. The server assigns `stop_key`; do **not** send it in the body (400 if sent). `{}` is valid for a placeholder stop. Returns 201 with the public normalized stop object (`address_reference_number` when resolved; **no** `address_id`). Can also resolve by ERP `location_reference_number` (Address v2 required). ## Request URI ```
- **statuses:** 201, 400, 401, 403, 404

**Parameters**

- `Content-Type` (header) type=string example=`application/json`
- `Authorization` (header) type=string example=`Token your_token_here` — Replace 'your_token_here' with your token.
- `draft_id` (path, required) type=string pattern=`^SD[-\d]+$` example=`SD12345678` — Draft reference number returned on create. Pattern: `SD` followed by digits (e.g. `SD12345678`).

**Request body** (required; application/json)

Schema (resolved summary):

```json
{
  "type": "string"
}
```

Example:

```json
{}
```

**Success `201`** — Public normalized stop object

```json
{
  "type": "string"
}
```

**Errors**

- `400`
- `401`
- `403`
- `404`

#### `PATCH /api/1/requests/draft/{draft_id}/stops/{stop_key}/`

- **operationId:** `patchStop`
- **summary:** Update Stop
- **description:** Partial update of one stop by `stop_key`. Do not send `stop_key` in the body (400 if sent). Unknown stop returns 404. Returns 200 with the updated public stop object (includes `location_reference_number` when set; **no** `address_id`). ## Request URI ``` PATCH {ENV_DOMAIN}/api/1/requests/draft/{draft_id}/stops/{stop_key}/ Content-Type: application/json
- **statuses:** 200, 400, 401, 403, 404

**Parameters**

- `Content-Type` (header) type=string example=`application/json`
- `Authorization` (header) type=string example=`Token your_token_here` — Replace 'your_token_here' with your token.
- `draft_id` (path, required) type=string pattern=`^SD[-\d]+$` example=`SD12345678` — Draft reference number returned on create. Pattern: `SD` followed by digits (e.g. `SD12345678`).
- `stop_key` (path, required) type=string example=`pickup-1` — Server-assigned stop key (e.g. `pickup-1`, `delivery-1`).

**Request body** (required; application/json)

Schema (resolved summary):

```json
{
  "type": "string"
}
```

Example:

```json
{
  "stop_notes": "Dock 3 only",
  "stop_contact_name": "Updated Contact"
}
```

**Success `200`** — Updated public stop object

```json
{
  "type": "string"
}
```

**Errors**

- `400`
- `401`
- `403`
- `404`

#### `DELETE /api/1/requests/draft/{draft_id}/stops/{stop_key}/`

- **operationId:** `deleteStop`
- **summary:** Delete Stop
- **description:** Remove one stop by `stop_key`. Returns 204. Clears `pickup_stop_key` / `delivery_stop_key` on linked packing-list lines (sets them to `null`) but does **not** delete those lines. ## Request URI ``` DELETE {ENV_DOMAIN}/api/1/requests/draft/{draft_id}/stops/{stop_key}/ Authorization: Token your_token_here ```
- **statuses:** 204, 401, 403, 404

**Parameters**

- `Authorization` (header) type=string example=`Token your_token_here` — Replace 'your_token_here' with your token.
- `draft_id` (path, required) type=string pattern=`^SD[-\d]+$` example=`SD12345678` — Draft reference number returned on create. Pattern: `SD` followed by digits (e.g. `SD12345678`).
- `stop_key` (path, required) type=string example=`pickup-1` — Server-assigned stop key (e.g. `pickup-1`, `delivery-1`).

**Success `204`** — No content

**Errors**

- `401`
- `403`
- `404`

#### `POST /api/1/requests/draft/{draft_id}/create/`

- **operationId:** `convertDraftOrDryRun`
- **summary:** Convert Draft
- **description:** Convert an accessible SYSTEM or REGULAR_NEXT_UI draft into a quote request, or validate the same rules without creating a shipment. ### Dry run (`dry_run: true`) Runs full convert validation **without** creating a Shipment. Draft is retained. - Success: `200` `{ "valid": true, "draft_id": "..." }` - Failure: `400` with field errors ### Convert (`dry_run` omitted or `false`)
- **statuses:** 200, 201, 400, 401, 403, 404

**Parameters**

- `Content-Type` (header) type=string example=`application/json`
- `Authorization` (header) type=string example=`Token your_token_here` — Replace 'your_token_here' with your token.
- `draft_id` (path, required) type=string pattern=`^SD[-\d]+$` example=`SD12345678` — Draft reference number returned on create. Pattern: `SD` followed by digits (e.g. `SD12345678`).

**Request body** (required; application/json)

Schema (resolved summary):

```json
{
  "type": "object",
  "properties": {
    "dry_run": {
      "type": "boolean",
      "description": "If true, validates without creating a shipment. Draft is retained.",
      "example": true
    },
    "auto_select_all_providers": {
      "type": "boolean",
      "description": "Invite all eligible providers from the private pool"
    },
    "skip_attachment_validation": {
      "type": "boolean",
      "description": "Skip attachment completeness checks during convert/dry-run"
    }
  }
}
```

Example:

```json
{
  "dry_run": true,
  "auto_select_all_providers": true,
  "skip_attachment_validation": false
}
```

**Success `200`** — Dry run success — draft is valid and retained

```json
{
  "type": "object",
  "properties": {
    "valid": {
      "type": "boolean",
      "example": true
    },
    "draft_id": {
      "type": "string",
      "description": "Draft reference that was validated (draft is retained)",
      "example": "D12345678"
    }
  },
  "required": [
    "valid",
    "draft_id"
  ]
}
```

Example:

```json
{
  "valid": true,
  "draft_id": "D12345678"
}
```

**Success `201`** — Draft successfully converted to quote request

```json
{
  "type": "object",
  "properties": {
    "shipment_reference": {
      "type": "string",
      "description": "New quote-request / shipment reference (e.g. `S12345678`)",
      "example": "S12345678"
    },
    "shipment_id": {
      "type": "integer",
      "description": "Numeric shipment id",
      "example": 12345678
    },
    "draft_reference_number": {
      "type": "string",
      "description": "Draft that was converted (row is deleted after success)",
      "example": "D12345678"
    }
  },
  "required": [
    "shipment_reference",
    "shipment_id",
    "draft_reference_number"
  ]
}
```

Example:

```json
{
  "shipment_reference": "S12345678",
  "shipment_id": 12345678,
  "draft_reference_number": "D12345678"
}
```

**Errors**

- `400`
- `401`
- `403`
- `404`

#### Tag: Quote Requests

#### `POST /api/1/requests/create/`

- **summary:** Create Request
- **description:** The Request CREATE end-point can be used to generate quote requests on Cargobase. This end-point can be used to create and send out full quote requests to your freight forwarders. Based on the details provided, all available providers will be invited. This means that some data is mandatory. Typically, this end-point is used to connect automated systems, or systems in which the Cargobase functionality is fully integrated. For more generic implementations, such as with ERP systems, we strongly adv
- **statuses:** 200

**Parameters**

- `Content-Type` (header) type=string example=`application/json`
- `Authorization` (header) type=string example=`Token your_token_here` — Replace 'your_token_here' with your token.

**Request body** (required; application/json)

Schema (resolved summary):

```json
{
  "type": "object",
  "properties": {}
}
```

Example:

```json
{
  "organization": {
    "location": "SL2963758",
    "quoting_deadline_date": "2022-03-25",
    "quoting_deadline_time": "12:00",
    "confirmation_date": "2022-03-30",
    "confirmation_time": "12:00",
    "custom_longfield_01": "My longfield input",
    "title": "1629256678058",
    "good_items": [
      {
        "handling_unit": "box",
        "units": 1,
        "length": 60,
        "height": 60,
        "width": 60,
        "m_unit": "cm",
        "weight": 200,
        "w_unit": "kg",
        "stackable": false,
        "hazardous": false,
        "is_dangerous_good": false,
        "additional_information": "TAKE CARE",
        "dangerous_good_value": "3",
        "container_type": null,
        "nmfc_class": "50",
        "good_customs_information": [
          {
            "value": 8000,
            "currency_code": "USD",
            "description": "Gear R",
            "hs_code": "E2"
          }
        ]
      }
    ]
  },
  "service": {
    "incoterm": "EXW",
    "insurance": true,
    "insurance_instructions": "AIA",
    "service_requirement": "DTD",
    "export_clearance": "3",
    "export_clearance_instructions": "NO",
    "transit_clearance": "1",
    "transit_clearance_instructions": "Sure",
    "import_clearance": "0",
    "import_clearance_instructions": "Checking",
    "air_charter_invited": false,
    "next_flight_invited": false,
    "ocean_freight_invited": false,
    "rail_freight_invited": false,
    "regular_air_freight_invited": true,
    "road_freight_invited": false,
    "road_freight_type": ""
  },
  "schedule": {
    "pickup_street": "CleanTech",
    "pickup_address_name": "01#03, STech",
    "pickup_state": "Singapore",
    "pickup_zipcode": "119932",
    "pickup_city": "Singapore",
    "pickup_country": "Singapore",
    "pickup_date": "2022-03-20",
    "pickup_time": "09:00:00",
    "pickup_contact_name": "ARTC",
    "pickup_contact_phone": "69095381",
    "pickup_contact_email": "artc@artc.a-star.edu.sg",
    "pickup_notes": "CHECK",
    "stop1_street": "Plot E261, Industrial Area, Sector 74\r\n\r\nPhase 8B",
    "stop1_address_name": "56#87, SpeedWide",
    "stop1_state": "Punjab",
    "stop1_zipcode": "160071",
    "stop1_city": "Mohali",
    "stop1_country": "India",
    "stop1_date": "2022-04-01",
    "stop1_time": "09:00:00",
    "stop1_contact_name": "Arcstone Pte. Ltd.",
    "stop1_contact_phone": "69095381",
    "stop1_contact_email": "arcstone@arcstone.co",
    "stop1_notes": "CHECK"
  }
}
```

**Success `200`** — Successful response

#### `GET /api/1/requests/`

- **summary:** List view
- **description:** The Request List View end-point provides a list of Requests associated with the requesting user. ## Request URI ``` GET https://pluto.cargobase.com/api/1/requests/ Content-Type: application/json Authorization: Token your_token_here ``` ## Status codes
- **statuses:** 200, default

**Parameters**

- `Authorization` (header) type=string example=`Token your_token_here` — Replace 'your_token_here' with your token.

**Success `200`** — OK

```json
{
  "type": "object",
  "properties": {}
}
```

Example:

```json
{
  "results": [
    {
      "quote_request_reference": "S93345678",
      "quote_request_title": "Latest Request",
      "freight_modes": "On board courier (OBC)",
      "shipper": "Shipper Demo Inc",
      "quotes_count": 0,
      "status": "New",
      "pickup_city": "Changchun",
      "pickup_country": "China",
      "stop1_city": "Regensburg",
      "stop1_country": "Germany",
      "modified": "2021-05-21 06:42:14"
    },
    {
      "quote_request_reference": "S92345678",
      "quote_request_title": "Second latest Request",
      "freight_modes": "Next flight out (NFO)",
      "shipper": "Shipper Demo Inc",
      "quotes_count": 1,
      "status": "Canceled",
      "pickup_city": "Taguig",
      "pickup_country": "Philippines",
      "stop1_city": "Cuautla",
      "stop1_country": "Mexico",
      "modified": "2021-05-21 04:39:12"
    },
    {
      "quote_request_reference": "S82345678",
      "quote_request_title": "Third Latest Request",
      "freight_modes": "On board courier (OBC)",
      "shipper": "Shipper Demo Inc",
      "quotes_count": 1,
      "status": "Uninvited",
      "pickup_city": "Kumamoto",
      "pickup_country": "Japan",
      "stop1_city": "Babenhausen",
      "stop1_country": "Germany",
      "modified": "2021-05-21 02:14:01"
    },
    {
      "quote_request_reference": "S72345678",
      "quote_request_title": "Fourth Latest Request",
      "freight_modes": "On board courier (OBC)",
      "shipper": "Shipper Demo Inc",
      "quotes_count": 1,
      "status": "New",
      "pickup_city": "Tlajomulco de Zuñiga, Jalisco, México.",
      "pickup_country": "Mexico",
      "stop1_city": "Bognor Regis",
      "stop1_country": "United Kingdom",
      "modified": "2021-05-21 01:47:34"
    },
    {
      "quote_request_reference": "S62345678",
      "quote_request_title": "Fifth Latest Request",
      "freight_modes": "Road freight",
      "shipper": "Shipper Demo Inc",
      "quotes_count": 0,
      "status": "New",
      "pickup_city": "Puebla",
      "pickup_country": "Mexico",
      "stop1_city": "Puebla",
      "stop1_country": "Mexico",
      "modified": "2021-05-21 01:46:34"
    },
    {
      "quote_request_reference": "S52345678",
      "quote_request_title": "Sixth Latest Request",
      "freight_modes": "On board courier (OBC)",
      "shipper": "Shipper Demo Inc",
      "quotes_count": 1,
      "status": "Quoted",
      "pickup_city": "Nogales",
      "pickup_country": "United States",
      "stop1_city": "Tlajomulco de Zuñiga, Jalisco, México.",
      "stop1_country": "Mexico",
      "modified": "2021-05-20 23:57:27"
    },
    {
      "quote_request_reference": "S42345678",
      "quote_request_title": "Seventh Latest Request",
      "freight_modes": "Road freight",
      "shipper": "Shipper Demo Inc",
      "quotes_count": 0,
      "status": "Opened",
      "pickup_city": "Culiacan",
      "pickup_country": "Mexico",
      "stop1_city": "Ciudad Juarez",
      "stop1_country": "Mexico",
      "modified": "2021-05-20 23:55:11"
    },
    {
      "quote_request_reference": "S32345678",
      "quote_request_title": "Eight Latest Request",
      "freight_modes": "On board courier (OBC), Next flight out (NFO)",
      "shipper": "Shipper Demo Inc",
      "quotes_count": 1,
      "status": "New",
      "pickup_city": "hangzhou, zhejiang",
      "pickup_country": "China",
      "stop1_city": "Santa Teresa",
      "stop1_country": "United States",
      "modified": "2021-05-20 22:29:41"
    },
    {
      "quote_request_reference": "S22345678",
      "quote_request_title": "Nineth Latest Request",
      "freight_modes": "Road freight",
      "shipper": "Shipper Demo Inc",
      "quotes_count": 0,
      "status": "New",
      "pickup_city": "Santa Teresa",
      "pickup_country": "United States",
      "stop1_city": "Buchanan",
      "stop1_country": "United States",
      "modified": "2021-05-20 22:17:52"
    },
    {
      "quote_request_reference": "S12345678",
      "quote_request_title": "Tenth 
  /* truncated */
```

#### `POST /api/1/quotes/`

- **summary:** Submit Quote
- **description:** The Submit Quote end-point can be used to post Quotes on requests. This end-point is only available to providers. Additionally, providers can only quote on requests they have been invited for. **Note** This end-point only applies to Providers **Note** Currently only Regular Air freight, NFO, OBC, Road and Ocean quotes are supported - additional freight modes will follow. ## Request URI ``` POST https://pluto.cargobase.com/api/1/quotes Content-Type: application/json
- **statuses:** 200

**Parameters**

- `Content-Type` (header) type=string example=`application/json`
- `Authorization` (header) type=string example=`Token your_token_here` — Replace 'your_token_here' with your token.

**Request body** (required; application/json)

Schema (resolved summary):

```json
{
  "type": "object",
  "properties": {}
}
```

Example:

```json
{
  "organization": {
    "provider_team": "PT12345678",
    "quoted_by": "quotes@example.com",
    "shipment_id": "S12345678"
  },
  "service": {
    "freight_mode": "Regular air freight",
    "quote_title": "Regular air freight quote",
    "primary_tracking_number": "REF-1001",
    "chargeable_weight": 120,
    "weight_UOM": "kg"
  },
  "financial": {
    "quote_currency": "USD",
    "not_included": "Destination charges and customs clearance are excluded.",
    "cost_details": {
      "air_freight_charges": 4.5,
      "additional_cost_data": [
        {
          "additional_cost_description": "Fuel surcharge",
          "additional_cost_item_amount": 85
        }
      ]
    }
  },
  "schedule": {
    "expected_pickup_date": "2026-10-08",
    "expected_pickup_time": "09:00",
    "expected_stop1_date": "2026-10-12",
    "expected_stop1_time": "16:00",
    "quote_valid_until_date": "2026-10-06",
    "quote_valid_until_time": "17:00",
    "flights": [
      {
        "airline_code": "LH",
        "flight_number": "400",
        "departure_date": "2026-10-09",
        "departure_time": "10:20",
        "departure_airport_code": "FRA",
        "arrival_date": "2026-10-10",
        "arrival_time": "13:05",
        "arrival_airport_code": "SIN"
      }
    ]
  }
}
```

**Success `200`** — Successful response

#### `GET /api/1/quotes/`

- **summary:** Quotes List
- **description:** The Quote List end-point can be used to retrieve a list of quotes submitted by you for a given shipment. ## Request URI ``` GET https://pluto.cargobase.com/api/1/quotes?shipment=S12345678 Content-Type: application/json Authorization: Token your_token_here ``` ## Query Parameter
- **statuses:** 200

**Parameters**

- `Content-Type` (header) type=string example=`application/json`
- `Authorization` (header) type=string example=`Token your_token_here` — Replace 'your_token_here' with your token.
- `shipment` (query) type=string example=`S12345678` — Replace S12345678 with the shipment ID.

**Success `200`** — Successful response

#### `PUT /api/1/requests/{shipment_reference}/`

- **summary:** Update Request
- **description:** The Request CREATE end-point can be used to generate quote requests on Cargobase, but also to update minor details on that request. This is useful, if you rely on your internal order/shipping platform to create requests in Cargobase. The options for updating your requests via API are purposefully rather limited at this moment. Any changes to allow more updates are not foreseen until an additional feature request is made. At this moment, the PUT action can only be used to update Pickup notes, Del
- **statuses:** 200

**Parameters**

- `Authorization` (header) type=string example=`Token your_token_here` — Replace 'your_token_here' with your token.
- `shipment_reference` (path, required) type=string pattern=`^S[-\d]+$` example=`S12345678` — Shipment reference number (e.g. `S12345678`).

**Request body** (optional; application/json)

Schema (resolved summary):

```json
{
  "type": "object",
  "properties": {}
}
```

Example:

```json
{
  "organization": {
    "additional_comments": "Please quote both your fastest and your most economical option.",
    "request_status": "canceled",
    "cancel_reason": 1,
    "cancel_comment": "This quote request will be canceled, in favor of a larger request coming tomorrow."
  },
  "schedule": {
    "pickup_notes": "Please park at loading bay 3, watch out for the Garden Gnome when turning in.",
    "stop1_notes": "Make sure to ring twice"
  }
}
```

**Success `200`** — Successful response

#### `GET /api/1/requests/{shipment_reference}/`

- **summary:** Request Detail
- **description:** The Request Detail end-point can be used to retrieve all specifics of a request. After a request has been awarded, the details can still be viewed, however: the Shipment Detail end-point should be approached for up to date data. ## Request URI ``` GET https://pluto.cargobase.com/api/1/requests/`SHIPMENT_ID` Authorization: Token your_token_here ``` ## Status codes
- **statuses:** 200

**Parameters**

- `Authorization` (header) type=string example=`Token your_token_here` — Replace 'your_token_here' with your token.
- `shipment_reference` (path, required) type=string pattern=`^S[-\d]+$` example=`S12345678` — Replace S12345678 with the relevant Shipment ID

**Success `200`** — Successful response

#### `PUT /api/1/requests/{shipment_reference}/assign/`

- **summary:** Assign team
- **description:** ## Purpose A simple end-point to assign a provider team. This is needed before submitting a quote, or in case a rate-card is available but multiple teams could apply for the same request. ## Access A provider can only assign teams associated with their account. PUT actions for other shipments or teams are rejected. An access token is required to POST to this end-point. Contact [support@cargobase.com](mailto:support@cargobase.com?subject=Token) to obtain your token. ## Request URI ```
- **statuses:** 200

**Parameters**

- `Authorization` (header) type=string example=`Token your_token_here` — Replace 'Your_token' with your own token.
- `shipment_reference` (path, required) type=string pattern=`^S[-\d]+$` example=`S12345678` — Replace with the Shipment ID of the request.

**Request body** (optional; application/json)

Schema (resolved summary):

```json
{
  "type": "object",
  "properties": {}
}
```

Example:

```json
{
  "provider_reference": "PT12345678"
}
```

**Success `200`** — Successful response

#### `PUT /api/1/quotes/{quotation_reference}/`

- **summary:** Update Quote
- **description:** The Update Quote end-point can be used to update existing Quotes submitted by you. This end-point is only available to providers. Not all details can be updated - in some cases you should cancel the existing quote and submit an alternative. You can use this end-point to submit a cancelation. **Note** This end-point only applies to Providers ## Request URI ``` PUT https://pluto.cargobase.com/api/1/quotes/{quote_reference} Content-Type: application/json
- **statuses:** 200

**Parameters**

- `Content-Type` (header) type=string example=`application/json`
- `Authorization` (header) type=string example=`Token your_token_here` — Replace 'your_token_here' with your token.
- `quotation_reference` (path, required) type=string pattern=`^Q[-\d]+$` example=`Q12345678` — Quotation reference number (e.g. `Q12345678`).

**Request body** (required; application/json)

Schema (resolved summary):

```json
{
  "type": "object",
  "properties": {}
}
```

Example:

```json
{
  "organization": {
    "request_status": "Open",
    "quoted_by": "quotes@example.com"
  },
  "service": {
    "chargeable_weight": 575,
    "weight_UOM": "kg",
    "quote_title": "Air quote updated",
    "primary_tracking_number": "17612345678"
  },
  "financial": {
    "quote_currency": "EUR",
    "not_included": "Wait time is charged separately.",
    "cost_details": {
      "air_freight_charges": 2,
      "additional_cost_data": [
        {
          "additional_cost_description": "Pickup charge",
          "additional_cost_item_amount": 172
        }
      ]
    }
  }
}
```

**Success `200`** — Successful response

#### Tag: Shipments

#### `GET /api/1/shipments/`

- **summary:** List view
- **description:** The Shipment List View end-point provides a list of Shipments associated with the requesting user. ## Request URI ``` GET https://pluto.cargobase.com/api/1/shipments/ Content-Type: application/json Authorization: Token your_token_here ``` **Note** Shipments that have not yet been awarded are considered 'Requests' and are not yet available in this list.
- **statuses:** 200

**Parameters**

- `Authorization` (header) type=string example=`Token your_token_here` — Replace 'your_token_here' with your token.

**Success `200`** — OK

```json
{
  "type": "object",
  "properties": {}
}
```

Example:

```json
{
  "results": [
    {
      "shipment_reference": "S93345678",
      "shipment_title": "Latest Request",
      "freight_mode": "On board courier (OBC)",
      "primary_tracking": "",
      "status": "Booked",
      "pickup_city": "Changchun",
      "pickup_country": "China",
      "stop1_city": "Regensburg",
      "stop1_country": "Germany",
      "modified": "2021-05-21 06:42:14"
    },
    {
      "shipment_reference": "S92345678",
      "shipment_title": "Second latest Request",
      "freight_mode": "Next flight out (NFO)",
      "primary_tracking": "CR20130224",
      "status": "Booked",
      "pickup_city": "Taguig",
      "pickup_country": "Philippines",
      "stop1_city": "Cuautla",
      "stop1_country": "Mexico",
      "modified": "2021-05-21 04:39:12"
    },
    {
      "shipment_reference": "S82345678",
      "shipment_title": "Third Latest Request",
      "freight_mode": "On board courier (OBC)",
      "primary_tracking": "",
      "status": "Booked",
      "pickup_city": "Kumamoto",
      "pickup_country": "Japan",
      "stop1_city": "Babenhausen",
      "stop1_country": "Germany",
      "modified": "2021-05-21 02:14:01"
    },
    {
      "shipment_reference": "S72345678",
      "shipment_title": "Fourth Latest Request",
      "freight_mode": "On board courier (OBC)",
      "primary_tracking": "2105211440",
      "status": "In Transit",
      "pickup_city": "Tlajomulco de Zuñiga, Jalisco, México.",
      "pickup_country": "Mexico",
      "stop1_city": "Bognor Regis",
      "stop1_country": "United Kingdom",
      "modified": "2021-05-21 01:47:34"
    },
    {
      "shipment_reference": "S62345678",
      "shipment_title": "Fifth Latest Request",
      "freight_mode": "Road freight",
      "primary_tracking": "",
      "status": "In Transit",
      "pickup_city": "Puebla",
      "pickup_country": "Mexico",
      "stop1_city": "Puebla",
      "stop1_country": "Mexico",
      "modified": "2021-05-21 01:46:34"
    },
    {
      "shipment_reference": "S52345678",
      "shipment_title": "Sixth Latest Request",
      "freight_mode": "On board courier (OBC)",
      "primary_tracking": "A113",
      "status": "In Transit",
      "pickup_city": "Nogales",
      "pickup_country": "United States",
      "stop1_city": "Tlajomulco de Zuñiga, Jalisco, México.",
      "stop1_country": "Mexico",
      "modified": "2021-05-20 23:57:27"
    },
    {
      "shipment_reference": "S42345678",
      "shipment_title": "Seventh Latest Request",
      "freight_mode": "Road freight",
      "primary_tracking": "T1000-AS",
      "status": "In Transit",
      "pickup_city": "Culiacan",
      "pickup_country": "Mexico",
      "stop1_city": "Ciudad Juarez",
      "stop1_country": "Mexico",
      "modified": "2021-05-20 23:55:11"
    },
    {
      "shipment_reference": "S32345678",
      "shipment_title": "Eight Latest Request",
      "freight_mode": "On board courier (OBC), Next flight out (NFO)",
      "primary_tracking": "429106",
      "status": "Delayed",
      "pickup_city": "hangzhou, zhejiang",
      "pickup_country": "China",
      "stop1_city": "Santa Teresa",
      "stop1_country": "United States",
      "modified": "2021-05-20 22:29:41"
    },
    {
      "shipment_reference": "S22345678",
      "shipment_title": "Nineth Latest Request",
      "freight_mode": "Road freight",
      "primary_tracking": "493389",
      "status": "Delayed",
      "pickup_city": "Santa Teresa",
      "pickup_country": "United States",
      "stop1_city": "Buchanan",
      "stop1_country": "United States",
      "modified": "2021-05-20 22:17:52"
    },
    {
      "shipment_reference": "S12345678",
      "shipment_title": "Tenth Latest Request",
      "freight_mode": "On board courier (OBC)",
      "primary_tracking": "19840412",
      "status": "Incomplete",
      "pickup_city": "Xuhui",
      "pickup_country": "China",
      "stop1_city": "Tlajomulco de Zuñiga, Jalisco, México.",
      "stop1_country": "Mexico",
      "modified": "2021-05-20 21:5
  /* truncated */
```

#### `GET /api/1/shipments/{shipment_reference}/`

- **summary:** Shipment Detail
- **description:** The Shipment Detail end-point can be used to retrieve all specifics of a Shipment. However, please be aware; if a Shipment has not been awarded, you will need the Request Detail end-point to view the specifics. ## Request URI ``` GET https://pluto.cargobase.com/api/1/shipments/`SHIPMENT_ID` Authorization: Token your_token_here ``` ## Status codes
- **statuses:** 200

**Parameters**

- `Authorization` (header) type=string example=`Token your_token_here` — Replace 'your_token_here' with your token.
- `shipment_reference` (path, required) type=string pattern=`^S[-\d]+$` example=`S12345678` — Replace S12345678 with the corresponding Shipment ID

**Success `200`** — OK

```json
{
  "type": "object",
  "properties": {}
}
```

Example:

```json
{
  "organization": {
    "shipment_id": "S12345678",
    "requestor": "Alex van Kampen",
    "shipment_status": "In transit",
    "shipment_book_datetime": "2019-04-25 00:09:23",
    "shipment_approved_by": "Alex van Kampen",
    "shipment_booked_by": "Pavel Makarevich",
    "title": "Title of the Shipment",
    "location": "Singapore",
    "cost_center": "123.AB.44",
    "custom_field1": "",
    "reason_code": "AT - API Tutorial",
    "good_items": [
      {
        "units": 35,
        "handling_unit": "carton",
        "length": 23,
        "height": 13,
        "width": 17,
        "m_unit": "inch",
        "weight": 17,
        "w_unit": "lbs",
        "stackable": false,
        "hazardous": false,
        "crating_required": null,
        "is_dangerous_good": null,
        "crating_required_by_date": null,
        "other_instructions": "",
        "additional_information": "",
        "container_type": null,
        "refrigerated_container": null,
        "custom_size": "",
        "custom_size_dimension_unit": "meter",
        "dangerous_good_value": "",
        "good_customs_information": [
          {
            "value": 1,
            "currency_code": "USD",
            "description": "Blinker fluid",
            "hs_code": "",
            "good_customs_information_attachments": []
          }
        ]
      }
    ],
    "special_requirements": {
      "air_truck_required": null,
      "air_truck_additional_information": "",
      "shock_tilt_required": null,
      "shock_tilt_additional_information": "",
      "unique_handling_required": null,
      "unique_handling_additional_information": "",
      "chemical_magnetic_concerns": null,
      "chemical_magnetic_additional_information": "",
      "unique_warehousing_required": null,
      "unique_warehousing_additional_information": "",
      "special_transport_required": null,
      "special_transport_additional_information": "",
      "special_provider_requirements": null,
      "special_provider_additional_information": "",
      "special_lift_fixtures_required": null,
      "special_lift_fixtures_additional_information": ""
    }
  },
  "service": {
    "incoterm": "EXW",
    "delivery_service_level": null,
    "export_clearance": null,
    "export_clearance_instruction": null,
    "transit_clearance": null,
    "transit_clearance_instruction": null,
    "import_clearance": true,
    "import_clearance_instruction": "Provider should prepare proper import documentation",
    "insurance": false,
    "insurance_instructions": "",
    "service_requirement": "",
    "freight_mode": "Next flight out (NFO)",
    "provider": "Movers & Shakers",
    "quote_id": "Q44112234",
    "airline": "KLM",
    "flight_number": "836",
    "primary_tracking_number": "29471924719285",
    "mawb": "",
    "other_tracking_number": "",
    "road_freight_type": ""
  },
  "schedule": {
    "pickup_airport_code": null,
    "pickup_airport": null,
    "pickup_seaport_code": null,
    "pickup_seaport": null,
    "pickup_country": "Singapore",
    "pickup_postal_code": "429106",
    "pickup_state": null,
    "pickup_city": "Singapore",
    "pickup_addressline1": "6 Ean Kiam Place",
    "pickup_addressline2": "",
    "quoted_pickup_date": "2019-04-24",
    "quoted_pickup_time": "11:00:00",
    "actual_pickup_date": "2019-04-24",
    "actual_pickup_time": "18:00:00",
    "pickup_timezone": "GMT+8",
    "pickup_notes": "",
    "pickup_contact_name": "Alex van Kampen",
    "pickup_contact_phone": "+65 1234 5678",
    "pickup_contact_email": "hello@cargobase.com",
    "pickup_address_type": "Address",
    "stop1_airport_code": null,
    "stop1_airport": null,
    "stop1_seaport_code": null,
    "stop1_seaport": null,
    "stop1_country": "Netherlands",
    "stop1_postal_code": "1051ML",
    "stop1_state": null,
    "stop1_city": "Amsterdam",
    "stop1_addressline1": "Wichersstraat 48",
    "stop1_addressline2": "",
    "stop1_quoted_delivery_date": "2019-04-25",
    "stop1_quoted_delivery_time": 
  /* truncated */
```

#### `PUT /api/1/shipments/{shipment_reference}/`

- **summary:** Cancel shipment
- **description:** The Shipment detail end-point can be used to cancel any booked shipment. A cancelation should only be done if pickup has not truly occurred. Also, an LSP might charge a cancelation fee or still invoice the full quoted value of the shipment. The options of this end-point are intentionally limited. **Note** This end-point only applies to Shippers ## Request URI ``` PUT https://pluto.cargobase.com/api/1/shipments/S12345678 Content-Type: application/json Authentication: Token 'your_token_here' ```
- **statuses:** 200

**Parameters**

- `Authorization` (header) type=string example=`Token your_token_here` — Replace 'your_token_here' with your token.
- `shipment_reference` (path, required) type=string pattern=`^S[-\d]+$` example=`S12345678` — Shipment reference number (e.g. `S12345678`).

**Request body** (optional; application/json)

Schema (resolved summary):

```json
{
  "type": "object",
  "properties": {}
}
```

Example:

```json
{
  "organization": {
    "changed_by": "username@company.com",
    "shipment_status": "canceled",
    "cancel_comment": "This shipment will be canceled, we understand the LSP might charge a cancelation fee."
  }
}
```

**Success `200`** — Successful response

#### `POST /api/1/shipments/{shipment_reference}/tracking/create/`

- **summary:** Add tracking number
- **description:** ## Purpose Add one or more tracking numbers to an awarded shipment. Use this before (or alongside) posting milestones via `POST /api/1/carrier-tracking-webhook`. Only one **primary** tracking number is allowed per shipment. The shipment must be awarded and not archived. ## Request URI ``` POST {ENV_DOMAIN}/api/1/shipments/{shipment_reference}/tracking/create/ Content-Type: application/json Authorization: Token your_token_here
- **statuses:** 201, 400, 401, 403, 404

**Parameters**

- `shipment_reference` (path, required) type=string example=`S12345678` — Cargobase shipment reference (for example `S12345678`).

**Request body** (required; application/json)

Schema (resolved summary):

```json
{
  "type": "object",
  "properties": {
    "references": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "tracking_type": {
            "type": "string",
            "enum": [
              "primary"
            ],
            "example": "primary",
            "description": "Tracking reference type. Currently only `primary` is supported."
          },
          "tracking_number": {
            "type": "string",
            "description": "Tracking number to attach to the shipment.",
            "example": "1Z999AA10123456784"
          }
        },
        "required": [
          "tracking_type",
          "tracking_number"
        ]
      },
      "description": "One or more tracking numbers to add to the shipment."
    }
  },
  "required": [
    "references"
  ]
}
```

Example:

```json
{
  "references": [
    {
      "tracking_type": "primary",
      "tracking_number": "1Z999AA10123456784"
    }
  ]
}
```

**Success `201`** — Tracking number(s) added.

```json
{
  "type": "object",
  "properties": {
    "success": {
      "type": "boolean",
      "example": true
    },
    "data": {
      "type": "object",
      "properties": {
        "references": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "tracking_type": {
                "type": "string",
                "enum": [
                  "primary"
                ],
                "example": "primary",
                "description": "Tracking reference type. Currently only `primary` is supported."
              },
              "tracking_number": {
                "type": "string",
                "description": "Tracking number to attach to the shipment.",
                "example": "1Z999AA10123456784"
              }
            },
            "required": [
              "tracking_type",
              "tracking_number"
            ]
          },
          "description": "One or more tracking numbers to add to the shipment."
        }
      },
      "required": [
        "references"
      ],
      "example": {
        "references": [
          {
            "tracking_type": "primary",
            "tracking_number": "1Z999AA10123456784"
          }
        ]
      }
    },
    "msg": {
      "type": "string",
      "example": "1Z999AA10123456784 added successfully"
    }
  }
}
```

Example:

```json
{
  "success": true,
  "data": {
    "references": [
      {
        "tracking_type": "primary",
        "tracking_number": "1Z999AA10123456784"
      }
    ]
  },
  "msg": "1Z999AA10123456784 added successfully"
}
```

**Errors**

- `400` — Validation error (for example a primary tracking number already exists, or the shipment tracking limit was exceeded).

```json
{
  "success": false,
  "data": {},
  "msg": "Error while creating tracking number"
}
```
- `401` — Unauthorized. Invalid or missing authentication token.
- `403` — Forbidden. Token cannot manage tracking for this shipment.
- `404` — Shipment not found, not awarded, or archived.

#### Tag: Invoices

#### `GET /api/1/invoices/`

- **summary:** List view
- **description:** The Invoices List View end-point provides a list of Invoices associated with the requesting user. ## Request URI ``` GET https://pluto.cargobase.com/api/1/invoices/ Content-Type: application/json Authorization: Token your_token_here ``` ## Status codes
- **statuses:** 200

**Parameters**

- `Authorization` (header) type=string example=`Token your_token_here` — Replace 'your_token_here' with your token.
- `sort_by` (query) type=string — Sort invoices by submission date. Use `submit_date:ASC` for oldest first, or `submit_date:DESC` for newest first.

**Success `200`** — Successful response

#### `GET /api/1/invoices/{invoice_reference}`

- **summary:** Details
- **description:** The Invoice Detail end-point can be used to retrieve all specifics of an invoice. Please be aware; some shipments do have multiple invoices. ## Request URI ``` GET https://pluto.cargobase.com/api/1/invoices/`INVOICE_REFERENCE` Authorization: Token your_token_here ``` ## Status codes
- **statuses:** 200

**Parameters**

- `Authorization` (header) type=string example=`Token your_token_here` — Replace 'your_token_here' with your token.
- `invoice_reference` (path, required) type=string example=`i12345678` — Replace 'I12345678' with the actual invoice_reference

**Success `200`** — Successful response

#### `POST /api/1/invoice-status-update/{invoice_reference}`

- **summary:** Update Status
- **description:** Use this endpoint to approve or decline an invoice. ## Request URI ``` POST https://pluto.cargobase.com/api/1/invoice-status-update/{invoice_reference} Content-Type: application/json Authorization: Token your_token_here ```
- **statuses:** 201, 400, 403, 404

**Parameters**

- `Authorization` (header) type=string example=`Token your_token_here` — Replace 'your_token_here' with your token.
- `invoice_reference` (path, required) type=string example=`I12345678` — Unique invoice reference identifier

**Request body** (required; application/json)

Schema (resolved summary):

```json
{
  "type": "object",
  "properties": {
    "action": {
      "type": "string",
      "enum": [
        "approved",
        "declined"
      ],
      "description": "The action to apply to the invoice"
    },
    "comment": {
      "type": "string",
      "description": "Comment explaining the reason for action"
    }
  },
  "required": [
    "action",
    "comment"
  ]
}
```

Example:

```json
{
  "action": "approved",
  "comment": "Matches the awarded quote."
}
```

**Success `201`** — Status updated successfully

Example:

```json
{
  "success": true,
  "details": {
    "action": "declined",
    "comment": "Shubh is rejecting"
  }
}
```

**Errors**

- `400` — Invalid request or invoice already acted upon

```json
{
  "message": "The invoice is already Approved/Declined."
}
```
- `403` — Forbidden (invalid token or permission issue)
- `404` — Invoice not found

#### Tag: Tracking

#### `POST /api/1/carrier-tracking-webhook`

- **summary:** Post carrier tracking update
- **description:** ## Purpose Main provider endpoint for posting a single tracking update (milestone) — and optionally documents — onto a Cargobase shipment. > **Check a payload before you send it:** paste it into the [Payload Doctor](/tools/payload-doctor?endpoint=carrier-tracking-webhook) to see what the API will reject, or to get help with an error response. ## Access Providers can only post updates for shipments associated with their account. Posts for other shipments are rejected. ## Content types You can sen
- **statuses:** 200, 400, 401, 403

**Request body** (required; multipart/form-data, application/json)

Schema (resolved summary):

```json
{
  "type": "object",
  "properties": {
    "tracking_number": {
      "type": "string",
      "description": "Carrier / third-party tracking number that identifies this update. Updates are grouped and de-duplicated by tracking number.",
      "example": "OMNI-12345"
    },
    "tracking_type": {
      "type": "string",
      "description": "Free-text identifier for the source of the update, for example `primary` or your carrier slug. Use one stable value for your system. Not validated on this endpoint.",
      "example": "primary"
    },
    "tracking_update_text": {
      "type": "string",
      "description": "Human-readable description of the event, shown on the shipment timeline. When uploading a document, include the document type (POD, ARN, HBL, …). Used for duplicate detection.",
      "example": "Departed origin"
    },
    "tracking_status_tag": {
      "type": "string",
      "enum": [
        "BOOKED",
        "INTRANSIT",
        "DELAYED",
        "DELIVERED",
        "CANCELLED",
        "UNSPECIFIED"
      ],
      "example": "INTRANSIT",
      "description": "Normalized status for the event. Case-sensitive: send the uppercase value exactly as listed (`Delivered` or `intransit` is rejected). `DELIVERED` requires `actual_arrival_time`. See the status table i"
    },
    "mode_of_transport": {
      "type": "string",
      "enum": [
        "air_freight",
        "road_freight",
        "ocean_freight",
        "rail_freight",
        "parcel_freight"
      ],
      "example": "air_freight",
      "description": "Freight mode for the shipment. Also decides which `milestone_details.event_type` values are accepted."
    },
    "shipment_id": {
      "type": "string",
      "description": "Cargobase shipment reference (for example `S22316102`). Strongly recommended: without it the update is stored against the tracking number only, and the Cargobase shipment's status and timings are not ",
      "example": "S22316102"
    },
    "created_time": {
      "type": "string",
      "format": "date-time",
      "description": "When the event was recorded in your system (ISO 8601). Used as the event's timestamp on the shipment timeline; if omitted, the time Cargobase receives the update is used. Also used for duplicate detec",
      "example": "2026-09-30T08:10:00.000Z"
    },
    "event_time": {
      "type": "string",
      "format": "date-time",
      "description": "When the milestone occurred (ISO 8601). Include `Z` or an offset; times without one are stored without a timezone.",
      "example": "2026-09-30T08:15:00.000Z"
    },
    "event_time_with_timezone": {
      "type": "string",
      "format": "date-time",
      "description": "Same as `event_time`, with an explicit timezone offset when available.",
      "example": "2026-09-30T10:15:00.000+02:00"
    },
    "expected_departure_time": {
      "type": "string",
      "format": "date-time",
      "description": "Expected departure (ISO 8601). Updates the shipment's expected departure when `shipment_id` is set.",
      "example": "2026-09-30T12:00:00.000Z"
    },
    "expected_arrival_time": {
      "type": "string",
      "format": "date-time",
      "description": "Expected arrival / delivery (ISO 8601). Updates the shipment's expected arrival when `shipment_id` is set. Useful on in-transit updates.",
      "example": "2026-10-02T16:00:00.000Z"
    },
    "actual_departure_time": {
      "type": "string",
      "format": "date-time",
      "description": "Actual departure (ISO 8601). Updates the shipment's actual departure when `shipment_id` is set.",
      "example": "2026-09-30T12:05:00.000Z"
    },
    "actual_arrival_time": {
      "type": "string",
      "format": "date-time",
      "description": "Actual arrival / delivery (ISO 8601). **Required when `tracking_status_tag` is `DELIVERED`.** Updates the shipment's actual arrival when `shipment_id` is set.",
      "example": "2026-01-08T07:19:00.000Z"
    },
    "pod_acceptor": {
      "type": "string",
      "description": "Name of the person who signed for the delivery. Recorded on the shipment with `DELIVERED` updates.",
      "example": "Jane Doe"
    },
    "additional_info": {
      "type": "object",
      "properties": {},
      "description": "Free-form key/value object for extra carrier-specific data. Must be a JSON object (not an array or string).",
      "example": {
        "lane": "SIN-AMS",
        "vehicle_id": "TRK-44"
      }
    },
    "bill_of_lading": {
      "type": "object",
      "properties": {
        "bill_of_lading_number": {
          "type": "string",
          "description": "Bill of lading (B/L) number.",
          "example": "COSU6349613240"
        },
        "carrier_no": {
          "type": "string",
          "description": "SCAC code identifying the carrier.",
          "example": "COSU"
        },
        "container_no": {
          "type": "string",
          "description": "Container number (container shipments only).",
          "example": "BMOU1589176"
        }
      },
      "description": "Bill of lading / ocean identifiers."
    },
    "flight_information": {
      "type": "object",
      "properties": {
        "flight_number": {
          "type": "string",
          "description": "Flight number including the airline code.",
          "example": "MH197"
        },
        "airline": {
          "type": "string",
          "description": "Airline name.",
          "example": "Malaysia Airlines"
        }
      },
      "required": [
        "flight_number"
      ],
      "description": "Flight identifiers for air shipments. If you send this object, `flight_number` is required."
    },
    "location": {
      "type": "string",
      "description": "Where this event happened. `location.location_text` is shown on the timeline."
    },
    "from": {
      "type": "string",
      "description": "Origin / from location for the segment."
    },
    "to": {
      "type": "string",
      "description": "Destination / to location for
  /* truncated */
```

Example:

```json
{
  "tracking_number": "OMNI-12345",
  "shipment_id": "S22316102",
  "tracking_type": "primary",
  "mode_of_transport": "air_freight",
  "tracking_update_text": "Departed origin",
  "tracking_status_tag": "INTRANSIT",
  "event_time": "2026-09-30T08:15:00.000Z",
  "expected_arrival_time": "2026-10-02T16:00:00.000Z"
}
```

**Success `200`** — Tracking update processed (or no new updates).

```json
{
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "description": "Result message. `No new updates for Tracking Number …` means the update repeated an earlier one and was skipped (see *Duplicate updates*)."
    }
  }
}
```

Example:

```json
{
  "message": "Generic Tracking Event for Tracking Number OMNI-12345 has been processed successfully."
}
```

**Errors**

- `400` — Bad request. Malformed JSON returns `error`; everything else, including validation errors, returns `message`. See *Errors* in the description for causes and fixes.

```json
{
  "error": "Invalid JSON body"
}
```
- `401` — Not returned by this endpoint in practice: a missing or invalid token returns `403`.
- `403` — Forbidden. The token is missing or invalid, or the token's user does not have permission to post tracking updates.

```json
{
  "detail": "Authentication credentials were not provided."
}
```

### Shared schemas

#### `components.schemas.ErrorResponse`

```json
{
  "type": "object",
  "properties": {
    "detail": {
      "type": "string",
      "description": "Human-readable error message"
    },
    "message": {
      "type": "string"
    }
  }
}
```

#### `components.schemas.ValidationErrorBody`

```json
{
  "type": "object",
  "properties": {}
}
```

#### `components.schemas.PaginatedAddressList`

```json
{
  "type": "object",
  "properties": {
    "count": {
      "type": "integer",
      "description": "Total number of matching addresses",
      "example": 12
    },
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "reference_number": {
            "type": "string",
            "description": "Unique address reference. Use as stop `address_reference_number`.",
            "example": "A12345678"
          },
          "location_reference_number": {
            "type": "string",
            "description": "ERP location reference. Use as stop `location_reference_number`.",
            "example": "ERP-WH-01"
          },
          "name": {
            "type": "string"
          },
          "street": {
            "type": "string"
          },
          "street_line2": {
            "type": "string"
          },
          "zipcode": {
            "type": "string"
          },
          "city_name": {
            "type": "string"
          },
          "state_name": {
            "type": "string"
          },
          "country_name": {
            "type": "string"
          },
          "contact_name": {
            "type": "string"
          },
          "contact_number": {
            "type": "string"
          },
          "contact_email": {
            "type": "string",
            "format": "email"
          }
        }
      }
    }
  },
  "required": [
    "count",
    "results"
  ]
}
```

#### `components.schemas.PaginatedDraftList`

```json
{
  "type": "object",
  "properties": {
    "count": {
      "type": "integer",
      "description": "Total number of matching drafts",
      "example": 3
    },
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "draft_reference_number": {
            "type": "string",
            "example": "D12345678"
          },
          "external_id": {
            "type": "string",
            "example": "ERP_ID_1710000000"
          },
          "created": {
            "type": "string",
            "format": "date-time"
          },
          "modified": {
            "type": "string",
            "format": "date-time"
          },
          "title": {
            "type": "string"
          },
          "location": {
            "type": "string",
            "description": "Payment location (`cb_account_number`)"
          },
          "has_validation_errors": {
            "type": "boolean"
          }
        }
      }
    }
  },
  "required": [
    "count",
    "results"
  ]
}
```

#### `components.schemas.AddressObject`

```json
{
  "type": "object",
  "properties": {
    "reference_number": {
      "type": "string",
      "description": "Unique address reference. Use as stop `address_reference_number`.",
      "example": "A12345678"
    },
    "location_reference_number": {
      "type": "string",
      "description": "ERP location reference. Use as stop `location_reference_number`.",
      "example": "ERP-WH-01"
    },
    "name": {
      "type": "string"
    },
    "street": {
      "type": "string"
    },
    "street_line2": {
      "type": "string"
    },
    "zipcode": {
      "type": "string"
    },
    "city_name": {
      "type": "string"
    },
    "state_name": {
      "type": "string"
    },
    "country_name": {
      "type": "string"
    },
    "contact_name": {
      "type": "string"
    },
    "contact_number": {
      "type": "string"
    },
    "contact_email": {
      "type": "string",
      "format": "email"
    }
  }
}
```

#### `components.schemas.DraftSummary`

```json
{
  "type": "object",
  "properties": {
    "draft_reference_number": {
      "type": "string",
      "example": "D12345678"
    },
    "external_id": {
      "type": "string",
      "example": "ERP_ID_1710000000"
    },
    "created": {
      "type": "string",
      "format": "date-time"
    },
    "modified": {
      "type": "string",
      "format": "date-time"
    },
    "title": {
      "type": "string"
    },
    "location": {
      "type": "string",
      "description": "Payment location (`cb_account_number`)"
    },
    "has_validation_errors": {
      "type": "boolean"
    }
  }
}
```

#### `components.schemas.AttachmentRef`

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "description": "FileUpload database id"
    },
    "name": {
      "type": "string",
      "example": "extra.pdf"
    },
    "reference_number": {
      "type": "string",
      "description": "FileUpload reference (`FU…`)",
      "example": "FU12345678"
    },
    "file_extension": {
      "type": "string",
      "example": "pdf"
    },
    "url": {
      "type": "string",
      "format": "uri"
    }
  },
  "required": [
    "reference_number"
  ]
}
```

#### `components.schemas.BucketAttachment`

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer"
    },
    "file": {
      "type": "string",
      "description": "FileUpload reference (`FU…`)",
      "example": "FU84121391"
    },
    "filename": {
      "type": "string",
      "example": "certificate.pdf"
    },
    "url": {
      "type": "string",
      "format": "uri"
    },
    "bucket_name": {
      "type": "string",
      "example": "CERTIFICATE_OF_ORIGIN"
    }
  }
}
```

#### `components.schemas.GoodCustomsInformation`

```json
{
  "type": "object",
  "properties": {
    "value": {
      "type": "number",
      "description": "Monetary value of the product in this handling unit",
      "example": 8000
    },
    "currency_code": {
      "type": "string",
      "description": "3-letter ISO 4217 currency code",
      "example": "USD"
    },
    "description": {
      "type": "string",
      "example": "Spare parts"
    },
    "hs_code": {
      "type": "string",
      "description": "Harmonized System code",
      "example": "8483.40"
    }
  }
}
```

#### `components.schemas.PackingListItem`

```json
{
  "type": "object",
  "properties": {
    "line_key": {
      "type": "string",
      "description": "Caller or server line identifier"
    },
    "pickup_stop_key": {
      "type": "string",
      "description": "`stop_key` of the pickup stop for this line. Cleared to null if that stop is deleted.",
      "example": "pickup-1"
    },
    "delivery_stop_key": {
      "type": "string",
      "description": "`stop_key` of the delivery stop for this line. Cleared to null if that stop is deleted.",
      "example": "delivery-1"
    },
    "good_item_id": {
      "type": "integer"
    },
    "handling_unit": {
      "type": "string",
      "description": "Handling unit type. Standard values:\n\n`bag`, `box`, `carton`, `case`, `crate`, `container`, `pallet`, `tube`\n\nCompany-configured custom units are also accepted.\n",
      "example": "pallet"
    },
    "handling_unit_value": {
      "type": "string",
      "description": "For `handling_unit=container`, use `LCL` or `FCL`.\nOtherwise free text or `null`.\n",
      "example": "FCL"
    },
    "units": {
      "type": "integer",
      "description": "Quantity of this handling unit",
      "example": 2
    },
    "length": {
      "type": "number"
    },
    "width": {
      "type": "number"
    },
    "height": {
      "type": "number"
    },
    "m_unit": {
      "type": "string",
      "enum": [
        "cm",
        "inch"
      ],
      "example": "cm",
      "description": "Length/width/height unit"
    },
    "weight_piece": {
      "type": "number",
      "description": "Weight of one piece. Some flows also accept `total_kg` / `total_lbs`."
    },
    "w_unit": {
      "type": "string",
      "enum": [
        "kg",
        "lbs",
        "total_kg",
        "total_lbs"
      ],
      "example": "kg",
      "description": "Weight unit. Typical values: `kg`, `lbs`.\nSome flows use `total_kg` / `total_lbs`.\n"
    },
    "cbm_scope": {
      "type": "string",
      "enum": [
        "piece",
        "total"
      ],
      "example": "piece",
      "description": "Whether cubic measurements apply per piece or as a total"
    },
    "container_type": {
      "type": "string",
      "enum": [
        "1",
        "2",
        "3",
        "4",
        "5",
        "6",
        "7",
        "8",
        "9",
        "10",
        "11",
        "12",
        "13",
        "14",
        "15",
        "16",
        "17",
        "20",
        "21",
        "22",
        "23",
        "24",
        "25",
        "26"
      ],
      "example": "12",
      "description": "Integer stored as a string. Used when `handling_unit` is `container`.\n\n| Value | Meaning |\n| --- | --- |\n| 1 | 20ft Standard |\n| 2 | 20ft Open top |\n| 3 | 20ft Flatrack |\n| 4 | 20ft Flatrack Collapsib"
    },
    "temperature_control_required": {
      "type": "boolean"
    },
    "temperature_control_value": {
      "type": "string",
      "enum": [
        "1",
        "2",
        "3",
        "4",
        "5",
        "6"
      ],
      "description": "Temperature band. If `6`, also set `temperature_controlled_custom_value`.\n\n| Value | Meaning |\n| --- | --- |\n| 1 | Deep frozen: <-20°C |\n| 2 | Store frozen: -20°C |\n| 3 | Store at 2°–8°C |\n| 4 | Cool:"
    },
    "temperature_controlled_custom_value": {
      "type": "string",
      "description": "Required when `temperature_control_value` is `6` (Other)"
    },
    "is_dangerous_good": {
      "type": "boolean"
    },
    "dangerous_good_value": {
      "type": "string",
      "enum": [
        "1",
        "2",
        "3",
        "4",
        "5",
        "6",
        "7",
        "8",
        "9"
      ],
      "description": "UN hazard class (string `\"1\"`…`\"9\"`).\n\n| Value | Meaning |\n| --- | --- |\n| 1 | Explosive |\n| 2 | Gases |\n| 3 | Flammable liquids |\n| 4 | Flammable solids |\n| 5 | Oxidising |\n| 6 | Toxic & infectious |"
    },
    "nmfc_class": {
      "type": "string",
      "enum": [
        "50",
        "55",
        "60",
        "65",
        "70",
        "77.5",
        "85",
        "92.5",
        "100",
        "110",
        "125",
        "150",
        "175",
        "200",
        "250",
        "300",
        "400",
        "500"
      ],
      "example": "70",
      "description": "NMFC freight class"
    },
    "hazardous": {
      "type": "boolean"
    },
    "stackable": {
      "type": "boolean"
    },
    "handling_required": {
      "type": "boolean"
    },
    "crating_required": {
      "type": "boolean"
    },
    "additional_information": {
      "type": "string"
    },
    "good_customs_information": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "value": {
            "type": "number",
            "description": "Monetary value of the product in this handling unit",
            "example": 8000
          },
          "currency_code": {
            "type": "string",
            "description": "3-letter ISO 4217 currency code",
  /* truncated */
```

#### `components.schemas.StopBase`

```json
{
  "type": "object",
  "properties": {
    "stop_type": {
      "type": "integer",
      "enum": [
        1,
        2
      ],
      "example": 1,
      "description": "`1` = Pickup, `2` = Dropoff / Delivery"
    },
    "stop_time_type": {
      "type": "integer",
      "enum": [
        1,
        2,
        3,
        4
      ],
      "example": 2,
      "description": "`1` = Before, `2` = After, `3` = Between, `4` = ASAP"
    },
    "stop_address_type": {
      "type": "integer",
      "enum": [
        1,
        2,
        3
      ],
      "example": 1,
      "description": "`1` = Street address, `2` = Airport, `3` = Port / Seaport"
    },
    "stop_address_name": {
      "type": "string"
    },
    "stop_street": {
      "type": "string"
    },
    "stop_street_line2": {
      "type": "string"
    },
    "stop_zipcode": {
      "type": "string"
    },
    "stop_country_name": {
      "type": "string",
      "description": "Country name or ISO 3166 alpha-2 / alpha-3 code"
    },
    "stop_state_name": {
      "type": "string",
      "description": "State / province (typically US, Mexico, Canada)"
    },
    "stop_city_name": {
      "type": "string"
    },
    "stop_airport_code": {
      "type": "string",
      "description": "IATA airport code when `stop_address_type` is `2`",
      "example": "SIN"
    },
    "stop_airport_name": {
      "type": "string"
    },
    "stop_seaport_code": {
      "type": "string",
      "description": "UN/LOCODE when `stop_address_type` is `3`",
      "example": "SGSIN"
    },
    "stop_seaport_name": {
      "type": "string"
    },
    "stop_contact_name": {
      "type": "string"
    },
    "stop_contact_number": {
      "type": "string"
    },
    "stop_contact_email": {
      "type": "string",
      "format": "email"
    },
    "stop_after_date": {
      "type": "string",
      "format": "date",
      "description": "Used with `stop_time_type` After (`2`) or Between (`3`)"
    },
    "stop_after_time": {
      "type": "string",
      "format": "time"
    },
    "stop_before_date": {
      "type": "string",
      "format": "date",
      "description": "Used with `stop_time_type` Before (`1`) or Between (`3`)"
    },
    "stop_before_time": {
      "type": "string",
      "format": "time"
    },
    "stop_hours_start": {
      "type": "string",
      "description": "Location opening time, typically `HH:MM` or `HH:MM:SS`",
      "example": "08:00:00"
    },
    "stop_hours_end": {
      "type": "string",
      "description": "Location closing time, typically `HH:MM` or `HH:MM:SS`",
      "example": "17:00:00"
    },
    "stop_timezone": {
      "type": "string",
      "description": "IANA timezone name",
      "example": "Asia/Singapore"
    },
    "stop_notes": {
      "type": "string"
    },
    "address_reference_number": {
      "type": "string",
      "description": "Address v2 `reference_number`. Preferred over `address_id`.",
      "example": "A12345678"
    },
    "location_reference_number": {
      "type": "string",
      "description": "ERP location code. Address v2 required to resolve.",
      "example": "ERP-WH-01"
    }
  }
}
```

#### `components.schemas.StopInput`

```json
{
  "type": "string"
}
```

#### `components.schemas.StopOutput`

```json
{
  "type": "string"
}
```

#### `components.schemas.ClassicAddressType`

```json
{
  "type": "string",
  "enum": [
    "address",
    "airport",
    "seaport"
  ]
}
```

#### `components.schemas.CargoReadyPickup`

```json
{
  "type": "string",
  "enum": [
    "after",
    "between",
    "asap_delivery",
    "unspecified"
  ]
}
```

#### `components.schemas.CargoReadyDelivery`

```json
{
  "type": "string",
  "enum": [
    "before",
    "between",
    "asap_delivery",
    "unspecified"
  ]
}
```

#### `components.schemas.FormAddressContactType`

```json
{
  "type": "string",
  "enum": [
    "consignee",
    "delivery",
    "custom"
  ]
}
```

#### `components.schemas.PartyAddress`

```json
{
  "type": "object",
  "properties": {
    "address_type": {
      "type": "string",
      "enum": [
        "address",
        "airport",
        "seaport"
      ],
      "description": "Classic string address type. Used on classic pickup/delivery fields\nand on consignee / notify party — **not** on `stops[]`.\n"
    },
    "form_address_contact_type": {
      "type": "string",
      "enum": [
        "consignee",
        "delivery",
        "custom"
      ],
      "description": "Classic consignee / notify-party contact type. **Not** used on `stops[]`."
    },
    "name": {
      "type": "string"
    },
    "street": {
      "type": "string"
    },
    "street_line2": {
      "type": "string"
    },
    "zipcode": {
      "type": "string"
    },
    "city_name": {
      "type": "string"
    },
    "state_name": {
      "type": "string"
    },
    "country_name": {
      "type": "string"
    },
    "contact_name": {
      "type": "string"
    },
    "contact_number": {
      "type": "string"
    },
    "contact_email": {
      "type": "string",
      "format": "email"
    },
    "airport_code": {
      "type": "string"
    },
    "airport_name": {
      "type": "string"
    },
    "seaport_code": {
      "type": "string"
    },
    "seaport_name": {
      "type": "string"
    }
  }
}
```

#### `components.schemas.ShipmentObject`

```json
{
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "example": "SG warehouse to NL DC"
    },
    "quoting_deadline_date": {
      "type": "string",
      "format": "date",
      "description": "Quote deadline date"
    },
    "quoting_deadline_time": {
      "type": "string",
      "format": "time",
      "description": "Quote deadline time of day"
    },
    "confirmation_date": {
      "type": "string",
      "format": "date"
    },
    "confirmation_time": {
      "type": "string",
      "format": "time"
    },
    "comments": {
      "type": "string"
    }
  }
}
```

#### `components.schemas.OrganizationalObject`

```json
{
  "type": "object",
  "properties": {
    "location": {
      "type": "string",
      "description": "`cb_account_number` of the payment location",
      "example": "SL2963758"
    },
    "invoice_location": {
      "type": "string",
      "description": "Organizational unit that should receive provider invoices"
    },
    "reason_code_group": {
      "type": "string"
    },
    "reason_code": {
      "type": "string"
    },
    "custom_field_01": {
      "type": "string"
    },
    "custom_field_02": {
      "type": "string"
    },
    "custom_field_03": {
      "type": "string"
    },
    "custom_long_field_01": {
      "type": "string"
    },
    "cost_center": {
      "type": "string"
    },
    "goods_confirmation_type": {
      "type": "string",
      "enum": [
        "Estimated",
        "Finalized"
      ],
      "example": "Estimated",
      "description": "Packing-list confirmation status"
    },
    "cost_recovery_required": {
      "type": "boolean"
    },
    "custom_cost_recovery_field1": {
      "type": "string"
    },
    "custom_cost_recovery_field2": {
      "type": "string"
    }
  }
}
```

#### `components.schemas.ScheduleObject`

```json
{
  "type": "object",
  "properties": {
    "multistop_instructions": {
      "type": "string"
    },
    "stops": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "consignee": {
      "type": "string"
    },
    "notify_party": {
      "type": "string"
    },
    "pickup_address_type": {
      "type": "string",
      "enum": [
        "address",
        "airport",
        "seaport"
      ],
      "description": "Classic string address type. Used on classic pickup/delivery fields\nand on consignee / notify party — **not** on `stops[]`.\n"
    },
    "stop1_address_type": {
      "type": "string",
      "enum": [
        "address",
        "airport",
        "seaport"
      ],
      "description": "Classic string address type. Used on classic pickup/delivery fields\nand on consignee / notify party — **not** on `stops[]`.\n"
    },
    "pickup_cargo_ready": {
      "type": "string",
      "enum": [
        "after",
        "between",
        "asap_delivery",
        "unspecified"
      ],
      "description": "Classic pickup cargo-ready window. **Not** used on `stops[]`."
    },
    "delivery_cargo_ready": {
      "type": "string",
      "enum": [
        "before",
        "between",
        "asap_delivery",
        "unspecified"
      ],
      "description": "Classic delivery cargo-ready window. **Not** used on `stops[]`."
    }
  }
}
```

#### `components.schemas.ScheduleObjectRead`

```json
{
  "type": "string"
}
```

#### `components.schemas.SpecialRequirementFlag`

```json
{
  "type": "object",
  "properties": {
    "value": {
      "type": "boolean",
      "description": "Whether this requirement is requested"
    },
    "additional_information": {
      "type": "string"
    }
  }
}
```

#### `components.schemas.ServiceObject`

```json
{
  "type": "object",
  "properties": {
    "incoterms": {
      "type": "string",
      "enum": [
        "None",
        "EXW",
        "FCA",
        "CPT",
        "CIP",
        "DAT",
        "DAP",
        "DDP",
        "FAS",
        "FOB",
        "CFR",
        "CIF",
        "DPU"
      ],
      "example": "DAP",
      "description": "Incoterms 2010/2020 code (`DAT` retained for compatibility; `DPU` is the 2020 successor)"
    },
    "incoterm_instructions": {
      "type": "string"
    },
    "service_type": {
      "type": "string",
      "enum": [
        "DTD",
        "DTP",
        "PTP",
        "PTD"
      ],
      "example": "DTD",
      "description": "| Value | Meaning |\n| --- | --- |\n| DTD | Door to door |\n| DTP | Door to port |\n| PTP | Port to port |\n| PTD | Port to door |\n"
    },
    "service_level": {
      "type": "string",
      "enum": [
        "1",
        "3",
        "5",
        "7",
        "NA"
      ],
      "example": "5",
      "description": "Requested transit service level in days, or `NA`"
    },
    "export_clearance": {
      "type": "string",
      "enum": [
        "no",
        "yes_other",
        "yes_internal",
        "yes_provider"
      ],
      "description": "| Value | Meaning |\n| --- | --- |\n| no | Not requested |\n| yes_other | Yes — arranged by another party |\n| yes_internal | Yes — arranged internally by the shipper |\n| yes_provider | Yes — provider sho"
    },
    "transit_clearance": {
      "type": "string",
      "enum": [
        "no",
        "yes_other",
        "yes_internal",
        "yes_provider"
      ],
      "description": "Same enum as `export_clearance`"
    },
    "import_clearance": {
      "type": "string",
      "enum": [
        "no",
        "yes_other",
        "yes_internal",
        "yes_provider"
      ],
      "description": "Same enum as `export_clearance`"
    },
    "export_clearance_instructions": {
      "type": "string"
    },
    "transit_clearance_instructions": {
      "type": "string"
    },
    "import_clearance_instructions": {
      "type": "string"
    },
    "insurance": {
      "type": "boolean"
    },
    "insurance_instructions": {
      "type": "string"
    },
    "special_requirements": {
      "type": "object",
      "properties": {},
      "description": "Map of location-configured requirement labels to\n`{ \"value\": true|false, ... }`.\n"
    }
  }
}
```

#### `components.schemas.InvitedModes`

```json
{
  "type": "object",
  "properties": {
    "OBC": {
      "type": "boolean",
      "description": "On board courier"
    },
    "air_charter": {
      "type": "boolean"
    },
    "NFO": {
      "type": "boolean",
      "description": "Next flight out"
    },
    "regular_air": {
      "type": "boolean"
    },
    "road_freight": {
      "type": "boolean"
    },
    "ocean_freight": {
      "type": "boolean"
    },
    "parcel": {
      "type": "boolean"
    },
    "rail_freight": {
      "type": "boolean"
    },
    "road_freight_option": {
      "type": "string",
      "enum": [
        "ftl",
        "ltl",
        "ge",
        "spe",
        "multi-stop",
        "multi-drop"
      ],
      "description": "Required when `road_freight` is `true`.\n\n| Value | Meaning |\n| --- | --- |\n| ftl | Full truck load |\n| ltl | Less than truck load |\n| ge | Ground expedite |\n| spe | Specialized (car haulers, flat-beds"
    },
    "custom": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {}
      },
      "description": "Company-specific custom mode entries"
    }
  }
}
```

#### `components.schemas.InvitedProviders`

```json
{
  "type": "object",
  "properties": {
    "providers": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Accepts provider ids, provider references, names, or slugs.\nResponse stores canonical provider references (e.g. `PT12345678`).\n"
    },
    "parcel_accounts": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  }
}
```

#### `components.schemas.DraftCreateInput`

```json
{
  "type": "object",
  "properties": {
    "external_id": {
      "type": "string",
      "description": "External ERP identifier for this draft (e.g. `ERP_ID_{timestamp}`)",
      "example": "ERP_ID_1710000000"
    },
    "shipment": {
      "type": "object",
      "properties": {
        "title": {
          "type": "string",
          "example": "SG warehouse to NL DC"
        },
        "quoting_deadline_date": {
          "type": "string",
          "format": "date",
          "description": "Quote deadline date"
        },
        "quoting_deadline_time": {
          "type": "string",
          "format": "time",
          "description": "Quote deadline time of day"
        },
        "confirmation_date": {
          "type": "string",
          "format": "date"
        },
        "confirmation_time": {
          "type": "string",
          "format": "time"
        },
        "comments": {
          "type": "string"
        }
      },
      "description": "Shipment-level title, timers, and comments"
    },
    "organizational": {
      "type": "object",
      "properties": {
        "location": {
          "type": "string",
          "description": "`cb_account_number` of the payment location",
          "example": "SL2963758"
        },
        "invoice_location": {
          "type": "string",
          "description": "Organizational unit that should receive provider invoices"
        },
        "reason_code_group": {
          "type": "string"
        },
        "reason_code": {
          "type": "string"
        },
        "custom_field_01": {
          "type": "string"
        },
        "custom_field_02": {
          "type": "string"
        },
        "custom_field_03": {
          "type": "string"
        },
        "custom_long_field_01": {
          "type": "string"
        },
        "cost_center": {
          "type": "string"
        },
        "goods_confirmation_type": {
          "type": "string",
          "enum": [
            "Estimated",
            "Finalized"
          ],
          "example": "Estimated",
          "description": "Packing-list confirmation status"
        },
        "cost_recovery_required": {
          "type": "boolean"
        },
        "custom_cost_recovery_field1": {
          "type": "string"
        },
        "custom_cost_recovery_field2": {
          "type": "string"
        }
      },
      "description": "Organizational / accounting fields for the draft"
    },
    "schedule": {
      "type": "object",
      "properties": {
        "multistop_instructions": {
          "type": "string"
        },
        "stops": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "consignee": {
          "type": "string"
        },
        "notify_party": {
          "type": "string"
        },
        "pickup_address_type": {
          "type": "string",
          "enum": [
            "address",
            "airport",
            "seaport"
          ],
          "description": "Classic string address type. Used on classic pickup/delivery fields\nand on consignee / notify party — **not** on `stops[]`.\n"
        },
        "stop1_address_type": {
          "type": "string",
          "enum": [
            "address",
            "airport",
            "seaport"
          ],
          "description": "Classic string address type. Used on classic pickup/delivery fields\nand on consignee / notify party — **not** on `stops[]`.\n"
        },
        "pickup_cargo_ready": {
          "type": "string",
          "enum": [
            "after",
            "between",
            "asap_delivery",
            "unspecified"
          ],
          "description": "Classic pickup cargo-ready window. **Not** used on `stops[]`."
        },
        "delivery_cargo_ready": {
          "type": "string",
          "enum": [
            "before",
            "between",
            "asap_delivery",
            "unspecified"
          ],
          "description": "Classic delivery cargo-ready window. **Not** used on `stops[]`."
        }
      },
      "description": "Routing. Canonical writes use `stops[]` (integer enums).\n\nOptional classic fields (`pickup_address_type`, `pickup_cargo_ready`,\n`delivery_cargo_ready`, `stop1_address_type`) use **string** enums and\na"
    },
    "packing_list": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "line_key": {
            "type": "string",
            "description": "Caller or server line identifier"
          },
          "pickup_stop_key": {
            "type": "string",
            "description": "`stop_key` of the pickup stop for this line. Cleared to null if that stop is deleted.",
            "example": "pickup-1"
          },
          "delivery_stop_key": {
            "type": "string",
            "description": "`stop_key` of the delivery stop for this line. Cleared to null if that stop is deleted.",
            "example": "delive
  /* truncated */
```

#### `components.schemas.DraftPatchInput`

```json
{
  "type": "object",
  "properties": {
    "external_id": {
      "type": "string"
    },
    "shipment": {
      "type": "object",
      "properties": {
        "title": {
          "type": "string",
          "example": "SG warehouse to NL DC"
        },
        "quoting_deadline_date": {
          "type": "string",
          "format": "date",
          "description": "Quote deadline date"
        },
        "quoting_deadline_time": {
          "type": "string",
          "format": "time",
          "description": "Quote deadline time of day"
        },
        "confirmation_date": {
          "type": "string",
          "format": "date"
        },
        "confirmation_time": {
          "type": "string",
          "format": "time"
        },
        "comments": {
          "type": "string"
        }
      },
      "description": "Shipment-level title, timers, and comments"
    },
    "organizational": {
      "type": "object",
      "properties": {
        "location": {
          "type": "string",
          "description": "`cb_account_number` of the payment location",
          "example": "SL2963758"
        },
        "invoice_location": {
          "type": "string",
          "description": "Organizational unit that should receive provider invoices"
        },
        "reason_code_group": {
          "type": "string"
        },
        "reason_code": {
          "type": "string"
        },
        "custom_field_01": {
          "type": "string"
        },
        "custom_field_02": {
          "type": "string"
        },
        "custom_field_03": {
          "type": "string"
        },
        "custom_long_field_01": {
          "type": "string"
        },
        "cost_center": {
          "type": "string"
        },
        "goods_confirmation_type": {
          "type": "string",
          "enum": [
            "Estimated",
            "Finalized"
          ],
          "example": "Estimated",
          "description": "Packing-list confirmation status"
        },
        "cost_recovery_required": {
          "type": "boolean"
        },
        "custom_cost_recovery_field1": {
          "type": "string"
        },
        "custom_cost_recovery_field2": {
          "type": "string"
        }
      },
      "description": "Organizational / accounting fields for the draft"
    },
    "schedule": {
      "type": "object",
      "properties": {
        "multistop_instructions": {
          "type": "string"
        },
        "stops": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "consignee": {
          "type": "string"
        },
        "notify_party": {
          "type": "string"
        },
        "pickup_address_type": {
          "type": "string",
          "enum": [
            "address",
            "airport",
            "seaport"
          ],
          "description": "Classic string address type. Used on classic pickup/delivery fields\nand on consignee / notify party — **not** on `stops[]`.\n"
        },
        "stop1_address_type": {
          "type": "string",
          "enum": [
            "address",
            "airport",
            "seaport"
          ],
          "description": "Classic string address type. Used on classic pickup/delivery fields\nand on consignee / notify party — **not** on `stops[]`.\n"
        },
        "pickup_cargo_ready": {
          "type": "string",
          "enum": [
            "after",
            "between",
            "asap_delivery",
            "unspecified"
          ],
          "description": "Classic pickup cargo-ready window. **Not** used on `stops[]`."
        },
        "delivery_cargo_ready": {
          "type": "string",
          "enum": [
            "before",
            "between",
            "asap_delivery",
            "unspecified"
          ],
          "description": "Classic delivery cargo-ready window. **Not** used on `stops[]`."
        }
      },
      "description": "Routing. Canonical writes use `stops[]` (integer enums).\n\nOptional classic fields (`pickup_address_type`, `pickup_cargo_ready`,\n`delivery_cargo_ready`, `stop1_address_type`) use **string** enums and\na"
    },
    "packing_list": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "line_key": {
            "type": "string",
            "description": "Caller or server line identifier"
          },
          "pickup_stop_key": {
            "type": "string",
            "description": "`stop_key` of the pickup stop for this line. Cleared to null if that stop is deleted.",
            "example": "pickup-1"
          },
          "delivery_stop_key": {
            "type": "string",
            "description": "`stop_key` of the delivery stop for this line. Cleared to null if that stop is deleted.",
            "example": "delivery-1"
          },
          "good_item_id": {
            "type": "integer"
          },
          "handling_unit": {
          
  /* truncated */
```

#### `components.schemas.DraftDocument`

```json
{
  "type": "object",
  "properties": {
    "draft_reference_number": {
      "type": "string",
      "description": "Server-assigned draft reference number",
      "example": "D12345678"
    },
    "created": {
      "type": "string",
      "format": "date-time"
    },
    "modified": {
      "type": "string",
      "format": "date-time"
    },
    "has_validation_errors": {
      "type": "boolean"
    },
    "external_id": {
      "type": "string"
    },
    "shipment": {
      "type": "object",
      "properties": {
        "title": {
          "type": "string",
          "example": "SG warehouse to NL DC"
        },
        "quoting_deadline_date": {
          "type": "string",
          "format": "date",
          "description": "Quote deadline date"
        },
        "quoting_deadline_time": {
          "type": "string",
          "format": "time",
          "description": "Quote deadline time of day"
        },
        "confirmation_date": {
          "type": "string",
          "format": "date"
        },
        "confirmation_time": {
          "type": "string",
          "format": "time"
        },
        "comments": {
          "type": "string"
        }
      },
      "description": "Shipment-level title, timers, and comments"
    },
    "organizational": {
      "type": "object",
      "properties": {
        "location": {
          "type": "string",
          "description": "`cb_account_number` of the payment location",
          "example": "SL2963758"
        },
        "invoice_location": {
          "type": "string",
          "description": "Organizational unit that should receive provider invoices"
        },
        "reason_code_group": {
          "type": "string"
        },
        "reason_code": {
          "type": "string"
        },
        "custom_field_01": {
          "type": "string"
        },
        "custom_field_02": {
          "type": "string"
        },
        "custom_field_03": {
          "type": "string"
        },
        "custom_long_field_01": {
          "type": "string"
        },
        "cost_center": {
          "type": "string"
        },
        "goods_confirmation_type": {
          "type": "string",
          "enum": [
            "Estimated",
            "Finalized"
          ],
          "example": "Estimated",
          "description": "Packing-list confirmation status"
        },
        "cost_recovery_required": {
          "type": "boolean"
        },
        "custom_cost_recovery_field1": {
          "type": "string"
        },
        "custom_cost_recovery_field2": {
          "type": "string"
        }
      },
      "description": "Organizational / accounting fields for the draft"
    },
    "schedule": {
      "type": "string"
    },
    "packing_list": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "line_key": {
            "type": "string",
            "description": "Caller or server line identifier"
          },
          "pickup_stop_key": {
            "type": "string",
            "description": "`stop_key` of the pickup stop for this line. Cleared to null if that stop is deleted.",
            "example": "pickup-1"
          },
          "delivery_stop_key": {
            "type": "string",
            "description": "`stop_key` of the delivery stop for this line. Cleared to null if that stop is deleted.",
            "example": "delivery-1"
          },
          "good_item_id": {
            "type": "integer"
          },
          "handling_unit": {
            "type": "string",
            "description": "Handling unit type. Standard values:\n\n`bag`, `box`, `carton`, `case`, `crate`, `container`, `pallet`, `tube`\n\nCompany-configured custom units are also accepted.\n",
            "example": "pallet"
          },
          "handling_unit_value": {
            "type": "string",
            "description": "For `handling_unit=container`, use `LCL` or `FCL`.\nOtherwise free text or `null`.\n",
            "example": "FCL"
          },
          "units": {
            "type": "integer",
            "description": "Quantity of this handling unit",
            "example": 2
          },
          "length": {
            "type": "number"
          },
          "width": {
            "type": "number"
          },
          "height": {
            "type": "number"
          },
          "m_unit": {
            "type": "string",
            "enum": [
              "cm",
              "inch"
            ],
            "example": "cm",
            "description": "Length/width/height unit"
          },
          "weight_piece": {
            "type": "number",
            "description": "Weight of one piece. Some flows also accept `total_kg` / `total_lbs`."
          },
          "w_unit": {
            "type": "string",
            "enum": [
              "kg",
              "lbs",
              "total_kg",
              "total_lbs"
            ],
            "example": "kg",
            "des
  /* truncated */
```

#### `components.schemas.ConvertDraftInput`

```json
{
  "type": "object",
  "properties": {
    "dry_run": {
      "type": "boolean",
      "description": "If true, validates without creating a shipment. Draft is retained.",
      "example": true
    },
    "auto_select_all_providers": {
      "type": "boolean",
      "description": "Invite all eligible providers from the private pool"
    },
    "skip_attachment_validation": {
      "type": "boolean",
      "description": "Skip attachment completeness checks during convert/dry-run"
    }
  }
}
```

#### `components.schemas.DryRunSuccess`

```json
{
  "type": "object",
  "properties": {
    "valid": {
      "type": "boolean",
      "example": true
    },
    "draft_id": {
      "type": "string",
      "description": "Draft reference that was validated (draft is retained)",
      "example": "D12345678"
    }
  },
  "required": [
    "valid",
    "draft_id"
  ]
}
```

#### `components.schemas.ConvertSuccess`

```json
{
  "type": "object",
  "properties": {
    "shipment_reference": {
      "type": "string",
      "description": "New quote-request / shipment reference (e.g. `S12345678`)",
      "example": "S12345678"
    },
    "shipment_id": {
      "type": "integer",
      "description": "Numeric shipment id",
      "example": 12345678
    },
    "draft_reference_number": {
      "type": "string",
      "description": "Draft that was converted (row is deleted after success)",
      "example": "D12345678"
    }
  },
  "required": [
    "shipment_reference",
    "shipment_id",
    "draft_reference_number"
  ]
}
```

#### `components.schemas.CreateOrderRequest`

```json
{
  "type": "object",
  "properties": {
    "quick_request": {
      "type": "object",
      "properties": {
        "title": {
          "type": "string",
          "description": "Title of the order or request",
          "example": "Shipment Title"
        },
        "comments": {
          "type": "string",
          "description": "Additional comments or instructions",
          "example": "Sample Test comments."
        },
        "external_id": {
          "type": "string",
          "description": "External ID used to identify the order in external systems",
          "example": "sample_external_id"
        }
      },
      "description": "Basic request details"
    },
    "organizational": {
      "type": "object",
      "properties": {
        "location": {
          "type": "string",
          "description": "A reference to the 'location' the request is for, location references are shared by Cargobase.",
          "example": "L1234567"
        },
        "cost_center": {
          "type": "string",
          "description": "Associated cost center",
          "example": "CC12345"
        },
        "reason_code": {
          "type": "string",
          "description": "Code explaining reason for the shipment",
          "example": "RC67890"
        },
        "reason_code_group": {
          "type": "string",
          "description": "Group categorization for reason code",
          "example": "RCG112233"
        },
        "custom_field_01": {
          "type": "string",
          "description": "User-defined custom field 1",
          "example": "Custom Value 01"
        },
        "custom_field_02": {
          "type": "string",
          "description": "User-defined custom field 2",
          "example": "Custom Value 02"
        },
        "custom_field_03": {
          "type": "string",
          "description": "User-defined custom field 3",
          "example": "Custom Value 03"
        },
        "custom_long_field_01": {
          "type": "string",
          "description": "Extended custom field",
          "example": "Custom Long Field 01"
        },
        "goods_confirmation_type": {
          "type": "string",
          "enum": [
            "Estimated",
            "Finalized"
          ],
          "example": "Finalized",
          "description": "Goods confirmation type (Estimated or Finalized)"
        }
      },
      "required": [
        "location"
      ],
      "description": "Organizational metadata for cost tracking and reporting"
    },
    "schedule": {
      "type": "object",
      "properties": {
        "pickup_contact_name": {
          "type": "string"
        },
        "pickup_contact_phone": {
          "type": "string"
        },
        "pickup_contact_email": {
          "type": "string"
        },
        "pickup_address_type": {
          "type": "string",
          "enum": [
            "Address",
            "Seaport",
            "Airport"
          ],
          "example": "Address",
          "description": "Type of pickup address (e.g. Address, Seaport or Airport)"
        },
        "pickup_address_name": {
          "type": "string",
          "description": "Name/label of pickup address",
          "example": "Main Warehouse"
        },
        "pickup_company_name": {
          "type": "string",
          "description": "Name of the pickup company",
          "example": "Logistics Co."
        },
        "pickup_city": {
          "type": "string",
          "example": "New York"
        },
        "pickup_state": {
          "type": "string",
          "example": "NY"
        },
        "pickup_country": {
          "type": "string",
          "example": "USA"
        },
        "pickup_zipcode": {
          "type": "string"
        },
        "pickup_airport_code": {
          "type": "string",
          "description": "IATA code of pickup airport",
          "example": "JFK"
        },
        "pickup_airport": {
          "type": "string",
          "example": "John F. Kennedy International Airport"
        },
        "pickup_seaport": {
          "type": "string",
          "example": "Port of New York"
        },
        "pickup_seaport_code": {
          "type": "string",
          "example": "NYK"
        },
        "pickup_country_code": {
          "type": "string",
          "example": "US"
        },
        "pickup_before_date": {
          "type": "string",
          "format": "date",
          "description": "Latest acceptable pickup date",
          "example": "2024-07-20"
        },
        "pickup_before_time": {
          "type": "string",
          "description": "Latest acceptable pickup time",
          "example": "16:00:00"
        },
        "pickup_ready_date": {
          "type": "string",
          "format": "date",
          "description": "Earliest pickup readiness date",
          "example": "2024-07-15"
        },
        "pickup_ready_time": {
          "type": "string",
          "description": "Earliest pickup readine
  /* truncated */
```

#### `components.schemas.DraftAttachmentUploadInput`

```json
{
  "type": "object",
  "properties": {
    "file": {
      "type": "string",
      "format": "binary",
      "description": "File to upload (same type rules as common file upload)."
    },
    "filename": {
      "type": "string",
      "description": "Optional display name override.",
      "example": "extra.pdf"
    }
  },
  "required": [
    "file"
  ]
}
```

#### `components.schemas.DraftAttachmentUploadOutput`

```json
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "example": "extra.pdf"
    },
    "reference_number": {
      "type": "string",
      "example": "FU12345678"
    },
    "file_extension": {
      "type": "string",
      "example": "pdf"
    }
  },
  "required": [
    "name",
    "reference_number",
    "file_extension"
  ]
}
```

#### `components.schemas.CarrierTrackingWebhookPayload`

```json
{
  "type": "object",
  "properties": {
    "tracking_number": {
      "type": "string",
      "description": "Carrier / third-party tracking number that identifies this update. Updates are grouped and de-duplicated by tracking number.",
      "example": "OMNI-12345"
    },
    "tracking_type": {
      "type": "string",
      "description": "Free-text identifier for the source of the update, for example `primary` or your carrier slug. Use one stable value for your system. Not validated on this endpoint.",
      "example": "primary"
    },
    "tracking_update_text": {
      "type": "string",
      "description": "Human-readable description of the event, shown on the shipment timeline. When uploading a document, include the document type (POD, ARN, HBL, …). Used for duplicate detection.",
      "example": "Departed origin"
    },
    "tracking_status_tag": {
      "type": "string",
      "enum": [
        "BOOKED",
        "INTRANSIT",
        "DELAYED",
        "DELIVERED",
        "CANCELLED",
        "UNSPECIFIED"
      ],
      "example": "INTRANSIT",
      "description": "Normalized status for the event. Case-sensitive: send the uppercase value exactly as listed (`Delivered` or `intransit` is rejected). `DELIVERED` requires `actual_arrival_time`. See the status table i"
    },
    "mode_of_transport": {
      "type": "string",
      "enum": [
        "air_freight",
        "road_freight",
        "ocean_freight",
        "rail_freight",
        "parcel_freight"
      ],
      "example": "air_freight",
      "description": "Freight mode for the shipment. Also decides which `milestone_details.event_type` values are accepted."
    },
    "shipment_id": {
      "type": "string",
      "description": "Cargobase shipment reference (for example `S22316102`). Strongly recommended: without it the update is stored against the tracking number only, and the Cargobase shipment's status and timings are not ",
      "example": "S22316102"
    },
    "created_time": {
      "type": "string",
      "format": "date-time",
      "description": "When the event was recorded in your system (ISO 8601). Used as the event's timestamp on the shipment timeline; if omitted, the time Cargobase receives the update is used. Also used for duplicate detec",
      "example": "2026-09-30T08:10:00.000Z"
    },
    "event_time": {
      "type": "string",
      "format": "date-time",
      "description": "When the milestone occurred (ISO 8601). Include `Z` or an offset; times without one are stored without a timezone.",
      "example": "2026-09-30T08:15:00.000Z"
    },
    "event_time_with_timezone": {
      "type": "string",
      "format": "date-time",
      "description": "Same as `event_time`, with an explicit timezone offset when available.",
      "example": "2026-09-30T10:15:00.000+02:00"
    },
    "expected_departure_time": {
      "type": "string",
      "format": "date-time",
      "description": "Expected departure (ISO 8601). Updates the shipment's expected departure when `shipment_id` is set.",
      "example": "2026-09-30T12:00:00.000Z"
    },
    "expected_arrival_time": {
      "type": "string",
      "format": "date-time",
      "description": "Expected arrival / delivery (ISO 8601). Updates the shipment's expected arrival when `shipment_id` is set. Useful on in-transit updates.",
      "example": "2026-10-02T16:00:00.000Z"
    },
    "actual_departure_time": {
      "type": "string",
      "format": "date-time",
      "description": "Actual departure (ISO 8601). Updates the shipment's actual departure when `shipment_id` is set.",
      "example": "2026-09-30T12:05:00.000Z"
    },
    "actual_arrival_time": {
      "type": "string",
      "format": "date-time",
      "description": "Actual arrival / delivery (ISO 8601). **Required when `tracking_status_tag` is `DELIVERED`.** Updates the shipment's actual arrival when `shipment_id` is set.",
      "example": "2026-01-08T07:19:00.000Z"
    },
    "pod_acceptor": {
      "type": "string",
      "description": "Name of the person who signed for the delivery. Recorded on the shipment with `DELIVERED` updates.",
      "example": "Jane Doe"
    },
    "additional_info": {
      "type": "object",
      "properties": {},
      "description": "Free-form key/value object for extra carrier-specific data. Must be a JSON object (not an array or string).",
      "example": {
        "lane": "SIN-AMS",
        "vehicle_id": "TRK-44"
      }
    },
    "bill_of_lading": {
      "type": "object",
      "properties": {
        "bill_of_lading_number": {
          "type": "string",
          "description": "Bill of lading (B/L) number.",
          "example": "COSU6349613240"
        },
        "carrier_no": {
          "type": "string",
          "description": "SCAC code identifying the carrier.",
          "example": "COSU"
        },
        "container_no": {
          "type": "string",
          "description": "Container number (container shipments only).",
          "example": "BMOU1589
  /* truncated */
```

#### `components.schemas.CreateShipmentTrackingReference`

```json
{
  "type": "object",
  "properties": {
    "tracking_type": {
      "type": "string",
      "enum": [
        "primary"
      ],
      "example": "primary",
      "description": "Tracking reference type. Currently only `primary` is supported."
    },
    "tracking_number": {
      "type": "string",
      "description": "Tracking number to attach to the shipment.",
      "example": "1Z999AA10123456784"
    }
  },
  "required": [
    "tracking_type",
    "tracking_number"
  ]
}
```

#### `components.schemas.CreateShipmentTrackingInput`

```json
{
  "type": "object",
  "properties": {
    "references": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "tracking_type": {
            "type": "string",
            "enum": [
              "primary"
            ],
            "example": "primary",
            "description": "Tracking reference type. Currently only `primary` is supported."
          },
          "tracking_number": {
            "type": "string",
            "description": "Tracking number to attach to the shipment.",
            "example": "1Z999AA10123456784"
          }
        },
        "required": [
          "tracking_type",
          "tracking_number"
        ]
      },
      "description": "One or more tracking numbers to add to the shipment."
    }
  },
  "required": [
    "references"
  ]
}
```

#### `components.schemas.CarrierTrackingWebhookMultipart`

```json
{
  "type": "object",
  "properties": {
    "data": {
      "type": "string",
      "description": "Tracking payload as a JSON string. Same fields as CarrierTrackingWebhookPayload."
    },
    "documents": {
      "type": "string",
      "format": "binary",
      "description": "Document file to attach (POD, ARN, HBL, etc.). Omit for a milestone-only update. Repeat this key for multiple files."
    }
  },
  "required": [
    "data"
  ]
}
```

#### `components.schemas.CarrierTrackingLocation`

```json
{
  "type": "object",
  "properties": {
    "location_text": {
      "type": "string",
      "description": "Free-text location label. Shown with the update on the shipment timeline and used for duplicate detection.",
      "example": "Singapore Changi"
    },
    "name": {
      "type": "string",
      "description": "Location, airport or facility name.",
      "example": "Incheon International Airport"
    },
    "country": {
      "type": "string",
      "description": "Country name.",
      "example": "Singapore"
    },
    "country_code": {
      "type": "string",
      "description": "Two-letter ISO 3166-1 country code.",
      "example": "SG"
    },
    "state": {
      "type": "string",
      "description": "State or province.",
      "example": "Arkansas"
    },
    "unlocode": {
      "type": "string",
      "description": "UN/LOCODE (5 characters).",
      "example": "SGSIN"
    },
    "iata_code": {
      "type": "string",
      "description": "IATA airport code (3 letters).",
      "example": "SIN"
    },
    "icao_code": {
      "type": "string",
      "description": "ICAO airport code (4 letters).",
      "example": "WSSS"
    },
    "coordinates": {
      "type": "object",
      "properties": {
        "lat": {
          "type": "number",
          "format": "float",
          "description": "Latitude in decimal degrees.",
          "example": 1.3644
        },
        "lng": {
          "type": "number",
          "format": "float",
          "description": "Longitude in decimal degrees.",
          "example": 103.9915
        }
      },
      "required": [
        "lat",
        "lng"
      ],
      "description": "Geo coordinates. If you send this object, both `lat` and `lng` are required."
    }
  }
}
```


---

## Collection: `webhook` — Webhooks

- **Audience:** Shipper & Provider — outbound events FROM Cargobase TO your server
- **OpenAPI source:** `/oas/webhook.openapi.json` (download this if you need the raw contract)
- **Servers:** `https://{customer-webhook-host}` (Customer-managed webhook receiver URL)
- **Security schemes:**
  - `TokenAuth`: send header `Authorization` — value format described as: Token-based authentication (Django REST framework style). Format: `Token <access_token>` Example: `Token your_token_here`
- `BearerAuth`: http bearer

### Endpoint index

| Method | Path | Summary | Statuses |
|--------|------|---------|----------|
| `WEBHOOK` | `(inbound to you) shipmentUpdate` | Shipment Update | 200 |

### Operations (implement from these specs)

#### Tag: Webhooks

#### WEBHOOK `shipmentUpdate` ← Cargobase calls you

- **operationId:** `shipmentUpdateWebhook`
- **summary:** Shipment Update
- **note:** Cargobase POSTs this payload TO your HTTPS endpoint
- **description:** Tracking event information is sent to the webhook whenever tracking updates enter Cargobase. ## Sample JSON ```json { "tracking_number": "TG166222", "tracking_status_tag": "DELIVERED", "event_time": "2023-07-01T14:59:56.711", "event_time_with_timezone": "2032-04-23T10:20:30.400+02:30",
- **statuses:** 200

**Request body** (required; application/json)

Schema (resolved summary):

```json
{
  "type": "object",
  "properties": {
    "tracking_number": {
      "type": "string",
      "description": "Tracking number of the shipment",
      "example": "TG166222"
    },
    "external_shipment_id": {
      "type": "string",
      "description": "Shipment ID used to identify shipment in external systems",
      "example": "testshipmentid"
    },
    "tracking_status_tag": {
      "type": "string",
      "enum": [
        "BOOKED",
        "PICKUP",
        "INTRANSIT",
        "DELAYED",
        "DELIVERED",
        "CANCELLED",
        "UNSPECIFIED",
        "EST_ARRIVAL",
        "EST_PICKUP"
      ],
      "example": "DELIVERED",
      "description": "Current status tag of the tracking event, e.g., DELIVERED, IN_TRANSIT. For estimated events (EST_ARRIVAL, EST_PICKUP), the timestamps will be estimates of those events"
    },
    "event_time": {
      "type": "string",
      "format": "date-time",
      "description": "Timestamp of the event (local time) without timezone information.",
      "example": "2023-07-01T14:59:56.711"
    },
    "event_time_with_timezone": {
      "type": "string",
      "format": "date-time",
      "description": "Timestamp of the event including timezone information (if available).",
      "example": "2023-04-23T10:20:30.400+02:30"
    },
    "bill_of_lading": {
      "type": "object",
      "properties": {
        "bill_of_lading_number": {
          "type": "string",
          "description": "Unique bill of lading number.",
          "example": "COSU6349613240"
        },
        "carrier_no": {
          "type": "string",
          "description": "SCAC carrier number or code.",
          "example": "COSU"
        },
        "container_no": {
          "type": "string",
          "description": "Container number associated with the shipment.",
          "example": "BMOU1589176"
        }
      },
      "description": "Details from the bill of lading associated with this tracking event. (only for ocean freight)"
    },
    "location": {
      "type": "object",
      "properties": {
        "country_code": {
          "type": "string",
          "description": "ISO country code.",
          "example": "US"
        },
        "state": {
          "type": "string",
          "description": "State or province of the event location.",
          "example": "Arkansas"
        }
      },
      "description": "JSON object containing location information where the shipment update occurred"
    },
    "document_link": {
      "type": "string",
      "format": "uri",
      "description": "Link to a document related to this tracking event (e.g., POD, invoice).",
      "example": "https://getsamplefiles.com/filedownloadhere"
    }
  },
  "required": [
    "tracking_number",
    "external_shipment_id",
    "tracking_status_tag"
  ]
}
```

Example:

```json
{
  "tracking_number": "TG166222",
  "external_shipment_id": "S12345678",
  "tracking_status_tag": "DELIVERED",
  "event_time": "2026-10-10T16:40:00.000Z",
  "document_link": "https://example.com/pod/TG166222.pdf",
  "location": {
    "country_code": "NL"
  }
}
```

**Success `200`** — Webhook received successfully. Return 2xx to acknowledge delivery.

### Shared schemas

#### `components.schemas.ShipmentUpdateEvent`

```json
{
  "type": "object",
  "properties": {
    "tracking_number": {
      "type": "string",
      "description": "Tracking number of the shipment",
      "example": "TG166222"
    },
    "external_shipment_id": {
      "type": "string",
      "description": "Shipment ID used to identify shipment in external systems",
      "example": "testshipmentid"
    },
    "tracking_status_tag": {
      "type": "string",
      "enum": [
        "BOOKED",
        "PICKUP",
        "INTRANSIT",
        "DELAYED",
        "DELIVERED",
        "CANCELLED",
        "UNSPECIFIED",
        "EST_ARRIVAL",
        "EST_PICKUP"
      ],
      "example": "DELIVERED",
      "description": "Current status tag of the tracking event, e.g., DELIVERED, IN_TRANSIT. For estimated events (EST_ARRIVAL, EST_PICKUP), the timestamps will be estimates of those events"
    },
    "event_time": {
      "type": "string",
      "format": "date-time",
      "description": "Timestamp of the event (local time) without timezone information.",
      "example": "2023-07-01T14:59:56.711"
    },
    "event_time_with_timezone": {
      "type": "string",
      "format": "date-time",
      "description": "Timestamp of the event including timezone information (if available).",
      "example": "2023-04-23T10:20:30.400+02:30"
    },
    "bill_of_lading": {
      "type": "object",
      "properties": {
        "bill_of_lading_number": {
          "type": "string",
          "description": "Unique bill of lading number.",
          "example": "COSU6349613240"
        },
        "carrier_no": {
          "type": "string",
          "description": "SCAC carrier number or code.",
          "example": "COSU"
        },
        "container_no": {
          "type": "string",
          "description": "Container number associated with the shipment.",
          "example": "BMOU1589176"
        }
      },
      "description": "Details from the bill of lading associated with this tracking event. (only for ocean freight)"
    },
    "location": {
      "type": "object",
      "properties": {
        "country_code": {
          "type": "string",
          "description": "ISO country code.",
          "example": "US"
        },
        "state": {
          "type": "string",
          "description": "State or province of the event location.",
          "example": "Arkansas"
        }
      },
      "description": "JSON object containing location information where the shipment update occurred"
    },
    "document_link": {
      "type": "string",
      "format": "uri",
      "description": "Link to a document related to this tracking event (e.g., POD, invoice).",
      "example": "https://getsamplefiles.com/filedownloadhere"
    }
  },
  "required": [
    "tracking_number",
    "external_shipment_id",
    "tracking_status_tag"
  ]
}
```


---

## Done criteria

- [ ] Auth smoke succeeds
- [ ] In-scope use-cases implemented
- [ ] No staff `/api/4.0` in partner code