> ## Documentation Index
> Fetch the complete documentation index at: https://docs.haulstow.co/llms.txt
> Use this file to discover all available pages before exploring further.

# API reference

> A plain-language map of every v1 endpoint.

An endpoint is one HTTP method and path, such as `GET /deliveries`. Add the path to the base URL:

```text theme={null}
Sandbox base URL + path
https://sandbox.developer.haulstow.co/v1 + /deliveries

Complete URL
https://sandbox.developer.haulstow.co/v1/deliveries
```

The interactive endpoint pages in the navigation contain every field, example, header, and possible response. This page helps you choose the endpoint you need.

## Choose an endpoint

| Method | Path                                                | Required scope                   |
| ------ | --------------------------------------------------- | -------------------------------- |
| `POST` | `/quotes`                                           | `quotes:read`                    |
| `POST` | `/recipients`                                       | `recipients:write`               |
| `GET`  | `/recipients`                                       | `recipients:read`                |
| `GET`  | `/recipients/{recipient_id}`                        | `recipients:read`                |
| `POST` | `/recipients/{recipient_id}/addresses`              | `recipients:write`               |
| `GET`  | `/recipients/{recipient_id}/addresses`              | `recipients:read`                |
| `GET`  | `/recipient-addresses/{address_id}`                 | `recipients:read`                |
| `POST` | `/deliveries`                                       | `deliveries:write`               |
| `GET`  | `/deliveries`                                       | `deliveries:read`                |
| `GET`  | `/deliveries/{delivery_id}`                         | `deliveries:read`                |
| `GET`  | `/deliveries/{delivery_id}/events`                  | `deliveries:read`                |
| `POST` | `/deliveries/{delivery_id}/cancel`                  | `deliveries:write`               |
| `POST` | `/test-helpers/deliveries/{delivery_id}/transition` | `deliveries:write`, sandbox only |

`GET` means read data. `POST` means calculate, create, or change something. Text inside braces is a value you replace. For example:

```text theme={null}
/deliveries/{delivery_id}
              becomes
/deliveries/dlv_3f1a821cdb58498cbb52f4706545a089
```

## Common workflows

### Create a delivery quickly

Use `POST /deliveries` with an inline `recipient`. This creates or reuses the recipient and address while creating the delivery. See the [quickstart](/quickstart).

### Reuse a recipient on many deliveries

1. `POST /recipients` and save the returned `rcp_...` ID.
2. `POST /recipients/{recipient_id}/addresses` and save the returned `adr_...` ID.
3. Send both IDs in each later `POST /deliveries` request.

Use this approach when the same customer receives multiple deliveries.

### Show a delivery-history page

1. Call `GET /deliveries` with filters such as `status` or `external_id`.
2. Follow `meta.next_cursor` while `meta.has_more` is true.
3. Call `GET /deliveries/{delivery_id}` for one full snapshot.
4. Call `GET /deliveries/{delivery_id}/events` for its public timeline.

### Cancel a delivery

Call `POST /deliveries/{delivery_id}/cancel`. Cancellation works only before pickup. Cancelling an already-cancelled delivery returns the same cancelled delivery. Cancelling after pickup returns `409 DELIVERY_NOT_CANCELLABLE`.

## Visibility rules

Recipients and addresses belong to the HaulStow business, so two developer applications for the same business can reuse them. Deliveries belong to the developer application that created them. Another application receives `404` instead of learning that the delivery exists.

The public delivery model intentionally excludes cargo contents, line items, rider details, internal operational state, platform notes, settlement data, and fee overrides.

## IDs and filters

The letters at the beginning of an ID tell you what it identifies:

| Prefix | Resource          | Example                                |
| ------ | ----------------- | -------------------------------------- |
| `rcp_` | Recipient         | `rcp_3f1a821cdb58498cbb52f4706545a089` |
| `adr_` | Recipient address | `adr_3f1a821cdb58498cbb52f4706545a089` |
| `dlv_` | Delivery          | `dlv_3f1a821cdb58498cbb52f4706545a089` |
| `evt_` | Delivery event    | `evt_3f1a821cdb58498cbb52f4706545a089` |

Copy IDs exactly. Do not remove the prefix or try to use an internal order ID.

## Filters and pages

Delivery lists accept `status`, `external_id`, `created_after`, `created_before`, `cursor`, and `limit`. Recipient lists accept `cursor` and `limit`. Cursors are opaque and must be passed back unchanged.

Example: list the first 25 in-transit deliveries:

```bash theme={null}
curl "$HAULSTOW_BASE_URL/deliveries?status=in_transit&limit=25" \
  --header "Authorization: Bearer $HAULSTOW_API_KEY"
```

Example: find the delivery attached to your own order number:

```bash theme={null}
curl "$HAULSTOW_BASE_URL/deliveries?external_id=shop-order-1842" \
  --header "Authorization: Bearer $HAULSTOW_API_KEY"
```

See [polling and pagination](/polling) for how to use `next_cursor`.