---
title: "Deliveries"
description: "Create, list, retrieve, filter, and cancel deliveries."
---

# Deliveries

Deliveries are created from persisted quotes. The create request must send the same origin, destination, and parcel payload that produced the quote.

## Create a delivery

```http
POST /v1/deliveries
```

```bash
curl -X POST https://entrega.ao/v1/deliveries \
  -H "Authorization: Bearer $ENTREGA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "quote_id": "8c1e1a90-7f08-4b2c-9d5d-9a4ab7f59c0e",
    "company_id": "0b1e6fc0-a821-4be4-8bd7-df56b8c0caa4",
    "origin": {"address_line": "Rua 21 de Janeiro", "city": "Luanda", "province": "Luanda"},
    "destination": {"address_line": "Rua Marien Nguabi", "city": "Luanda", "province": "Luanda"},
    "parcel": {"weight_grams": 1200, "description": "Photo prints"},
    "payment_method": "prepaid",
    "options": {"metadata": {"checkout_id": "WEB-4821"}}
  }'
```

## Create fields

| Field | Required | Notes |
| --- | --- | --- |
| `quote_id` | Yes | Returned by `POST /v1/quotes`. |
| `company_id` | No | If present, must match the quote company. |
| `origin` | Yes | Must match the quote payload. |
| `destination` | Yes | Must match the quote payload. |
| `parcel` | Yes | Must match the quote payload. |
| `payment_method` | No | `prepaid`, `bank_transfer`, or `cod`. Defaults to `prepaid`. |
| `cash_collect_aoa` | Conditional | Required for cash-on-delivery flows. |
| `scheduled_pickup_at` | No | ISO8601 timestamp. |
| `scheduled_delivery_at` | No | ISO8601 timestamp. |
| `options.metadata` | No | Free-form metadata echoed in responses and webhooks. |

> Do not send `courier_fee_aoa`. Entrega rejects client-supplied courier fees with `courier_fee_aoa_not_accepted`.

## List and lookup

```http
GET /v1/deliveries
GET /v1/deliveries/{id}
DELETE /v1/deliveries/{id}
```

The list endpoint is paginated and tenant-scoped. It does not return a `total` count; use `pagination.has_more`.

## Supported filters

| Query param | Example | Behavior |
| --- | --- | --- |
| `status` | `pending` | Single status. |
| `status` | `pending,assigned,in_transit` | Comma-separated status list. |
| `inserted_at_gte` | `2026-02-01T00:00:00Z` | Created on or after timestamp. Inclusive. |
| `inserted_at_lte` | `2026-03-01T00:00:00Z` | Created on or before timestamp. Inclusive. |
| `sort` | `inserted_at_desc` | Newest first. Default. |
| `sort` | `inserted_at_asc` | Oldest first. |
| `search` | `DLV-2026` | Substring match on reference, origin/destination city, and address line. |
| `limit` | `50` | Page size. Minimum `1`, maximum `100`. |
| `offset` | `100` | Page offset. Maximum `100000`. |

## List examples

```bash
curl "https://entrega.ao/v1/deliveries?status=pending,assigned&limit=20" \
  -H "Authorization: Bearer $ENTREGA_SECRET_KEY"
```

```bash
curl "https://entrega.ao/v1/deliveries?inserted_at_gte=2026-02-01T00:00:00Z&inserted_at_lte=2026-03-01T00:00:00Z&sort=inserted_at_asc" \
  -H "Authorization: Bearer $ENTREGA_SECRET_KEY"
```

```bash
curl "https://entrega.ao/v1/deliveries?search=Maianga&offset=20&limit=20" \
  -H "Authorization: Bearer $ENTREGA_SECRET_KEY"
```

## Cancellable states

`DELETE /v1/deliveries/{id}` succeeds only when the delivery is `awaiting_payment`, `pending`, or `assigned`. Other states return `409 Conflict`.