# HaulStow Developer

> Build delivery workflows with HaulStow.

## Docs

- [HaulStow Developer API](https://docs.haulstow.co/index.md): A beginner-friendly guide to adding HaulStow deliveries to your app.
- [10-minute quickstart](https://docs.haulstow.co/quickstart.md): Copy, paste, and create your first simulated delivery.
- [Common errors](https://docs.haulstow.co/errors.md): Understand an error response and fix the most common problems.
- [API reference](https://docs.haulstow.co/reference.md): A plain-language map of every v1 endpoint.
- [Authentication](https://docs.haulstow.co/authentication.md): Learn where your API key goes and how to keep it safe.
- [Idempotency](https://docs.haulstow.co/idempotency.md): Safely retry a request without creating the same thing twice.
- [Poll delivery status](https://docs.haulstow.co/polling.md): Repeatedly check a delivery's status without wasting requests.
- [Webhooks](https://docs.haulstow.co/webhooks.md): Let HaulStow notify your server when a delivery changes.
- [Sandbox](https://docs.haulstow.co/sandbox.md): Safely practise the complete delivery flow with simulated data.
- [Create a delivery quote](https://docs.haulstow.co/api-reference/quotes/create-a-delivery-quote.md): Calculates a quote from pickup and drop-off coordinates. This operation does not create or reserve a delivery and does not require an `Idempotency-Key`.
- [List recipients](https://docs.haulstow.co/api-reference/recipients/list-recipients.md): Returns the authenticated business's recipient directory using opaque cursor pagination.
- [Create or reuse a recipient](https://docs.haulstow.co/api-reference/recipients/create-or-reuse-a-recipient.md): Normalizes the phone number and returns the existing recipient when the authenticated business already has the same normalized phone number. A new resource returns `201`; a reused resource returns `200`.
- [Get a recipient](https://docs.haulstow.co/api-reference/recipients/get-a-recipient.md): Returns one business-scoped recipient. Cross-business resources return `404`.
- [List a recipient's addresses](https://docs.haulstow.co/api-reference/recipients/list-a-recipients-addresses.md): Returns every reusable address owned by the business-scoped recipient.
- [Add or reuse a recipient address](https://docs.haulstow.co/api-reference/recipients/add-or-reuse-a-recipient-address.md): Adds a reusable address to a recipient. An exact normalized address match returns the existing address with `200`; a new address returns `201`.
- [Get a recipient address](https://docs.haulstow.co/api-reference/recipients/get-a-recipient-address.md): Returns one reusable address. Cross-business resources return `404`.
- [List deliveries](https://docs.haulstow.co/api-reference/deliveries/list-deliveries.md): Returns only deliveries created by the authenticated application. Results are ordered by `(created_at, id)` and use opaque cursor pagination.
- [Create a delivery](https://docs.haulstow.co/api-reference/deliveries/create-a-delivery.md): Creates one delivery using either existing recipient/address IDs or one inline recipient. The two recipient shapes are mutually exclusive.
- [Get a delivery](https://docs.haulstow.co/api-reference/deliveries/get-a-delivery.md): Returns one public delivery. Cross-application and cross-business IDs return `404`.
- [List delivery events](https://docs.haulstow.co/api-reference/deliveries/list-delivery-events.md): Returns the public lifecycle timeline ordered by sequence. Prefer webhooks for real-time updates. If polling, fetch the delivery first and refetch events only after its `status` or `updated_at` changes.
- [Cancel a delivery](https://docs.haulstow.co/api-reference/deliveries/cancel-a-delivery.md): Cancels a delivery before pickup. Repeating cancellation for an already cancelled delivery returns the same representation. Cancellation after pickup returns `409 DELIVERY_NOT_CANCELLABLE`.
- [Advance a sandbox delivery](https://docs.haulstow.co/api-reference/sandbox/advance-a-sandbox-delivery.md): Advances a simulated delivery through an allowed forward transition and emits the same webhook contract used for live lifecycle changes. This endpoint is available only on the sandbox server and accepts only test keys.
- [Receive a delivery lifecycle event](https://docs.haulstow.co/api-reference/webhooks/receive-a-delivery-lifecycle-event.md): HaulStow sends this request to each active subscribed webhook endpoint. Delivery is at least once: deduplicate with the stable event `id`.

## OpenAPI Specs

- [openapi](https://docs.haulstow.co/openapi.yaml)