# Courier update, for orders with your own courier

`POST https://management.horeca-24.de/api/partner/v1/orders/{externalId}/delivery`

Only for orders with `fulfillment.courier: partner`; any other order answers `409 INVALID_TRANSITION`.

- `picked_up`: delivery status "on the way" in the till.
- `delivered`: delivery status "delivered"; the restaurant can complete the order.
- `assigned`, `arriving`: no change of the delivery status; the other fields still apply.
- `failed`: nothing changes in the till; our support is alerted. Cancel the order separately if needed.

`etaPickupAt` / `etaDropOffAt` set the pickup and drop-off times, `courier` the driver (the latest counts),
`trackingUrl` the tracking link. The order's status never changes by a courier update. An update that changes
nothing answers `changed: false`, so retries are safe.

## Headers

- `Authorization` (string, required): Bearer $PARTNER_API_KEY

## Path parameters

- `externalId` (string, required, pattern: `^[A-Za-z0-9._~-]{1,64}$`)
  Your order id, as sent in `POST /orders`.

## Request

`application/json`

- `status` (string, required, `assigned` | `arriving` | `picked_up` | `delivered` | `failed`)
- `etaPickupAt` (string, optional, format: date-time)
  ISO 8601 with Z or an offset
- `etaDropOffAt` (string, optional, format: date-time)
  ISO 8601 with Z or an offset
- `courier` (object, optional)
  - `name` (string, required, 1-200 chars)
  - `phone` (string, required, 1-50 chars)
- `trackingUrl` (string, optional, 0-2048 chars, format: uri)

## Response

### 200 — Taken

- `orderId` (string, required, pattern: `^oo_[0-9a-f]{64}$`)
  Our order id
- `externalId` (string, required, pattern: `^[A-Za-z0-9._~-]{1,64}$`)
  Your order id, unique per connection
- `changed` (boolean, required)
  false when the update changed nothing

## Errors

- `400`: An error; see `ErrorCode`
- `401`: `UNAUTHORIZED`: the key is missing, malformed, unknown, wrong, expired or revoked
- `403`: `CONNECTION_REVOKED`: the restaurant deleted the connection; stop sending
- `404`: An error; see `ErrorCode`
- `409`: An error; see `ErrorCode`
- `422`: An error; see `ErrorCode`
- `429`: `RATE_LIMITED`: 60 per minute and connection, shared by orders, cancel and delivery

## Code example (cURL)

```sh
curl -X POST https://management.horeca-24.de/api/partner/v1/orders/A/delivery \
  -H "Authorization: Bearer $PARTNER_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "status": "picked_up",
  "etaPickupAt": "2026-10-15T12:10:00Z",
  "etaDropOffAt": "2026-10-15T12:30:00Z",
  "courier": {
    "name": "Ali",
    "phone": "+49 151 000000"
  },
  "trackingUrl": "https://track.example/x"
}'
```

## Response 200 — Example

```json
{
  "orderId": "oo_5c1e2d3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d",
  "externalId": "A-1001",
  "changed": true
}
```