# MeowX Delivery API v1 — integration guide

API version `2026-11-04`. Two modes:

- **Test mode** (keys `mx_test_…`): a full sandbox. Nothing is dispatched or charged, prices are indicative, and you
  move deliveries through their statuses yourself.
- **Live mode** (keys `mx_live_…`): real deliveries by MeowX riders in Sydney, charged per delivery to the card your
  account owner saved in the MeowX Go app, at the same price as the app.

Build and test everything with a test key; going live is a key change, not a code change.

## Base URL and transport

- Base URL: provided by MeowX when your account is enabled (for example `https://api.meowx.com.au`).
- HTTPS and JSON only. Send `Content-Type: application/json` on requests with a body. Bodies are limited to 64 KB.
- Server-to-server only. The API sends no CORS headers: never put an API key in a browser, mobile app or public
  repository.

## Authentication

```
Authorization: Bearer mx_test_<key id>_<secret>
```

Your team uses the **MeowX Business portal** (https://meowx.com.au/business/portal/): MeowX invites the work email
on your agreement; register there with that email, verify it, and accept the invitation. Developers create test keys
there (MeowX operations can also issue test keys). **Live keys are created by your account owner in the
portal** and are shown **once**, to you only: MeowX staff never see a live key. MeowX stores only a
digest and cannot show any key again. If a key is lost or exposed, revoke it in the portal (MeowX can also revoke it
for you at once) and create a new one. Developers in your team can create test keys there too; only owners can create
live keys, with a verified email and after entering their password again.

| Scope | Allows |
|---|---|
| `quotes:write` | `POST /v1/quotes` |
| `deliveries:read` | `GET /v1/deliveries`, `GET /v1/deliveries/{id}`, `GET /v1/deliveries/{id}/cancellation` |
| `deliveries:write` | create and cancel deliveries; advance sandbox deliveries |

Test keys see only test data and live keys only live data. One business can never see another's deliveries.

## Idempotency

`POST /v1/deliveries` and `POST /v1/deliveries/{id}/cancel` **require** an `Idempotency-Key` header (8–255
characters: letters, digits, `_ - : .`). Use a value that identifies the operation in your system, such as your order
id.

- Retrying with the same key and body returns the original response with `Idempotent-Replayed: true`. **You are never
  charged twice**, even if the first attempt timed out on your side or ours.
- The same key with a different body is refused (`422 idempotency_key_reused`).
- A retry while the first request is still running gets `409 idempotency_request_in_progress`; retry shortly.
- If a live request answers `503 live_order_temporarily_unavailable`, retry with the **same** key: MeowX resumes the
  same order where it stopped.
- Keys are remembered for 24 hours.

## Rate limits

Each key has a per-minute limit (default 60). Responses carry `X-RateLimit-Limit`, `X-RateLimit-Remaining` and
`X-RateLimit-Reset` (unix seconds). Over the limit: `429 rate_limited` with `Retry-After` (seconds).

## Errors

```json
{"error": {"type": "invalid_request_error", "code": "parameter_missing",
  "message": "dropoff.phone is required.", "param": "dropoff.phone", "requestId": "req_5d1c0b2f8e7a4c3b9d6e1f00"}}
```

| HTTP | type | typical codes |
|---|---|---|
| 400 | `invalid_request_error` | `parameter_missing`, `parameter_invalid`, `parameter_unknown`, `invalid_json`, `idempotency_key_required` |
| 401 | `authentication_error` | `authentication_required`, `api_key_invalid`, `api_key_revoked`, `api_key_expired` |
| 402 | `payment_error` | `payment_declined`, `payment_authentication_required`, `payer_card_unavailable` |
| 403 | `permission_error` | `insufficient_scope`, `enterprise_inactive`, `sandbox_only`, `live_mode_unavailable`, `live_payer_not_configured`, `payer_unavailable` |
| 404 | `not_found_error` | `delivery_not_found`, `route_not_found`, `location_not_found` |
| 409 | `conflict_error` / `idempotency_error` | `delivery_not_cancellable`, `cancellation_fee_confirmation_required`, `cancellation_requires_support`, `cancellation_terms_changed`, `order_rejected`, `idempotency_request_in_progress` |
| 413 / 415 | `invalid_request_error` | `payload_too_large`, `unsupported_media_type` |
| 422 | `invalid_request_error` / `idempotency_error` | `outside_service_area`, `address_unverifiable`, `address_location_mismatch`, `same_pickup_and_dropoff`, `vehicle_not_serviceable`, `items_too_heavy`, `proof_of_delivery_unavailable`, `quote_expired`, `quote_mismatch`, `quote_not_found`, `quote_price_changed`, `location_not_found`, `location_limit_reached`, `idempotency_key_reused` |
| 429 | `rate_limit_error` | `rate_limited`, `route_quote_limit_reached` |
| 500 / 503 | `api_error` | `internal_error`, `api_unavailable`, `live_order_temporarily_unavailable`, `rate_limit_unavailable`, `route_unavailable` |

Unknown fields are rejected, not ignored. Quote the `requestId` (also in `MeowX-Request-Id`) when contacting MeowX.

## Objects

**Stop** (`pickup`, `dropoff`):

```json
{
  "name": "Sam Receiver",
  "phone": "+61498765432",
  "address": {"line1": "50 Bridge Rd", "line2": "Unit 4", "suburb": "Glebe", "state": "NSW", "postcode": "2037", "country": "AU"},
  "location": {"latitude": -33.8792, "longitude": 151.1856},
  "instructions": "Leave with reception"
}
```

Phones use the `+61` format. Send the coordinates of the door the rider should go to. In live mode MeowX checks that
the address and the coordinates describe the same place (within 150 m) and uses MeowX's standard form of the address
on the order. Quotes need only `address` and `location`.

A pickup can also be a saved location: `"pickup": {"locationId": "loc_…"}` (see "Pickup locations").

**Delivery**:

```json
{
  "id": "dlv_live_3f9a…",
  "object": "delivery",
  "mode": "live",
  "livemode": true,
  "status": "pending",
  "externalReference": "ORDER-1001",
  "quoteId": "qte_live_…",
  "pickup": {"…": "…"},
  "dropoff": {"…": "…"},
  "items": [{"description": "Flowers", "quantity": 1, "weightKg": 1.5}],
  "vehicle": "car",
  "proofOfDelivery": "photo",
  "notes": "",
  "notifications": {"recipientSms": true},
  "price": {"currency": "AUD", "totalCents": 1621, "gstCents": 147},
  "estimates": {"distanceKm": 3.4, "durationMinutes": 24},
  "rider": {"name": "Alex", "vehicle": "car"},
  "proof": null,
  "cancellation": null,
  "failure": null,
  "timeline": [{"status": "pending", "at": "2026-11-04T01:00:00.000Z"}],
  "trackingUrl": "https://meowx.com.au/t/Xk3p…/",
  "createdAt": "2026-11-04T01:00:00.000Z",
  "updatedAt": "2026-11-04T01:00:00.000Z"
}
```

- Statuses: `pending` → `rider_assigned` → `picked_up` → `delivered`; or `cancelled`; or `failed` (the delivery could
  not be completed).
- Vehicles: `bike` (bicycle or e-bike), `motorcycle`, `car` (default). If the items do not fit the vehicle you asked
  for, the quote is refused with `vehicle_not_serviceable`; use `car`.
- Proof of delivery: `photo`. (`pin` is available in test mode only for now.)
- Prices include GST. In live mode `price.totalCents` is exactly what is charged. Test-mode prices are indicative only
  (`"indicative": true`).
- `rider.name` is the rider's first name.

## Endpoints

### `GET /v1/ping`
Checks the key. Returns your `enterpriseId`, `keyId`, `mode` and `livemode`.

### `POST /v1/quotes`
Body: `pickup` (address and location, or `{"locationId": "loc_…"}`), `dropoff` (address and location), optional
`vehicle`, optional `items`. Returns a `quote` with `price`,
`estimates` and `expiresAt`. Live quotes last 10 minutes and their price is the charge if you order with them.

### `POST /v1/deliveries` (Idempotency-Key required)
Body: `externalReference` (your id, 1–64 characters), `pickup` (a full stop or `{"locationId": "loc_…"}`),
`dropoff` (a full stop), `items` (1–20, total weight at
most 60 kg), optional `quoteId`, `vehicle`, `proofOfDelivery`, `notes`, `notifications` (see "Tracking links and
recipient texts"). With `quoteId`, pickup, dropoff, vehicle and
items must match the quote and the quote must not have expired. Returns `201` with the delivery.

In live mode the delivery is charged to your registered card at once. If the price would differ from the quote you
saw, nothing is charged and you get `422 quote_price_changed`; request a new quote and retry with a new key. A
declined card gives `402` and nothing is dispatched.

### `GET /v1/deliveries/{id}`
Returns one delivery, or `404` if it does not exist for your business and mode.

### `GET /v1/deliveries`
Query: `limit` (1–100, default 20), `startingAfter` (a delivery id from the previous page) or `externalReference`.
Newest first. Returns `{"object": "list", "data": [...], "hasMore": true}`.

### `GET /v1/deliveries/{id}/cancellation`
The current cancellation terms:

```json
{"object": "cancellation_terms", "deliveryId": "dlv_live_…", "cancellable": true, "requiresSupport": false,
 "feeCents": 0, "currency": "AUD", "refundRatio": 1}
```

Cancelling before a rider accepts is free. After that a fee may apply, or the delivery may need MeowX support.

### `POST /v1/deliveries/{id}/cancel` (Idempotency-Key required)
Body: `reason` (`customer_cancelled`, `merchant_cancelled`, `duplicate`, `other`), optional `note`, and
`acceptFeeCents` — the fee you agree to, which must equal the current `feeCents` (default `0`). If the fee has changed
you get `409 cancellation_fee_confirmation_required` with the current amount. Refunds follow the MeowX cancellation
policy and go back to the card.

### `POST /v1/sandbox/deliveries/{id}/advance` (test keys only)
Simulates the rider. Body (optional): `{"to": "picked_up"}`; without `to` the delivery moves one step. Skipped steps
are recorded and each emits its event.

### Pickup locations

Save each store, kitchen or warehouse once, then send `"pickup": {"locationId": "loc_…"}` in quotes and deliveries
instead of the whole stop. A business keeps up to 50 locations; they work with test and live keys alike. The same
locations appear in the business portal at https://meowx.com.au/business/portal/, where people without a developer can
add them, book deliveries one at a time and upload a spreadsheet of up to 100.

- `GET /v1/locations` lists the active locations, by label: `{"object": "list", "data": [...]}`.
- `POST /v1/locations` (Idempotency-Key required) saves one. Body: `label` (1–60 characters, shown in the portal),
  optional `kind` (`store`, the default, or `warehouse` for an airport, port or freight warehouse) and `stop` (a
  full stop with name and phone). Returns `201`:

```json
{"id": "loc_6b0f…", "object": "location", "label": "Glebe kitchen", "kind": "store",
 "stop": {"name": "Acme Florist", "phone": "+61412345678", "address": {"…": "…"}, "location": {"…": "…"},
          "instructions": "Rear door on Wigram Rd"},
 "archived": false, "createdAt": "2026-11-07T01:00:00.000Z", "updatedAt": "2026-11-07T01:00:00.000Z"}
```

- `POST /v1/locations/{id}/archive` stops new orders from using it (repeating it is harmless). Deliveries already
  made keep the stop they were booked with.
- An archived or unknown `locationId` gives `422 location_not_found` with `param` `pickup.locationId`; a 51st
  location gives `422 location_limit_reached`.
- Reading needs `deliveries:read`; saving and archiving need `deliveries:write`.

### Route quotes (preview)

Price many drop-offs from one pickup as trips. MeowX splits them into trips that fit the vehicle (car: up to 15 stops,
120 kg and 3 hours; motorbike: 6 stops, 30 kg and 2.5 hours; bike: 3 stops, 15 kg and 2 hours), puts each trip in a
short order, and prices each whole trip the way a single delivery of that distance and time is priced, plus three
minutes and A$2.50 (car) or A$2.00 (motorbike, bike) for each extra stop. The answer also shows what the same parcels
cost as separate deliveries.

- With live keys every leg is measured on real roads, with the same routing as MeowX's own deliveries, and each trip
  is priced exactly as a delivery of that distance and time costs today (`"distanceSource": "roads"`); a one-stop trip
  costs the same as a normal delivery. Live route quotes need the same approved payer card as live orders. A business
  can measure up to 3000 road legs a day (`429 route_quote_limit_reached` after that); `503 route_unavailable` means a
  road route could not be computed, and there is no straight-line fallback.
- Test keys get an estimate from straight-line distances (`"distanceSource": "estimate"`).
- Route quotes are indicative and cannot be booked directly (`"indicative": true`). For a firm, bookable multi-stop
  plan, use the trip endpoints below.

- `POST /v1/route_quotes` (scope `quotes:write`). Body: `pickup` (address and location, or `{"locationId": "loc_…"}`),
  `dropoffs` (1–100, each with `address` and `location`, optional `reference` and `weightKg`) and optional `vehicle`
  (`car`, the default, `motorcycle` or `bike`). Returns `200`:

```json
{"object": "route_quote", "indicative": true, "vehicle": "car", "currency": "AUD", "distanceSource": "roads",
 "trips": [{"index": 0, "distanceKm": 24.9, "durationMinutes": 98, "totalCents": 12336,
            "stops": [{"dropoffIndex": 3, "reference": "AWB-1004", "etaMinutes": 9}, {"…": "…"}]}],
 "totals": {"trips": 1, "stops": 12, "totalCents": 12336, "separateTotalCents": 36217, "savingsCents": 23881,
            "savingsBps": 6594},
 "createdAt": "2026-11-07T01:00:00.000Z"}
```

### Multi-stop trips (live keys)

When multi-stop booking is enabled, `POST /v1/trip_quotes` (scope `quotes:write`) returns stored, bookable plans.
Provide `pickup` as a full delivery stop, `vehicle` (`car`, `motorcycle` or `bike`) and `parcels` (1–50).
Every parcel has a unique `reference`, a full `dropoff` stop and `items`, with optional `notes` and `notifications`.
Stops use the same names, Australian phone numbers, structured addresses and coordinates as a normal delivery.
The portal can resolve a saved pickup location for you; API callers must supply its full stop details.

The server verifies all addresses and actual road legs, orders the stops and splits the parcels by vehicle capacity,
weight and route time, including a possible return. Each returned `trips[]` entry contains `id`, `price.totalCents`,
`returnFee.totalCents`, `stops[]` (with parcel references and addresses) and `expiresAt`.
Display both the delivery price and conditional return fee before booking. All amounts are AUD cents including GST.
Test keys may use indicative route quotes; they cannot create these live trip plans.

Book each plan with `POST /v1/trips` (scope `deliveries:write`, **Idempotency-Key required**):

```json
{"planId":"etp_0123456789abcdef0123456789abcdef","externalReference":"TRIP-1001","acceptReturnFeeCents":715}
```

Use the exact `returnFee.totalCents` from the plan. Booking charges the saved business card once for that trip and
returns a normal delivery object with `trip` details. Read its progress through `GET /v1/deliveries/{id}`.
If a response is lost, retry the same plan, body and idempotency key. For several plans, keep each successful result
and retry only the unconfirmed plans. Do not create replacement plans while an earlier booking is unresolved.

The rider photographs each handover. If a parcel cannot be handed over after five minutes at its stop, the rider
records the reason and photo, finishes the other stops, then brings undelivered parcels back to the pickup location.
The disclosed return fee is charged separately only after the return is completed. A declined return charge is
shown as requiring collection; it does not change completed deliveries or the rider's earned income.

Each `trip.stops[]` entry has its own `trackingUrl` and status. Give a recipient only their own link.
The parent delivery has no shared recipient tracking link. A trip can finish with some stops `DELIVERED` and others
`RETURNED`; use the stop statuses to determine each parcel's outcome.

### Monthly statements (live keys)

Every live delivery is charged to your card when you book it and gets its own MeowX receipt. Once a month MeowX also
prepares a **statement** that summarises the previous calendar month (Australia/Sydney time). A statement is not a tax
invoice and nothing on it is payable. It is usually available on the 2nd of the month, and at the latest by the 8th.
Months without live deliveries or refunds have no statement. Statements contain no names, phone numbers or addresses.

- `GET /v1/statements` lists statements, newest first. Query: `limit` (1–24, default 12) and `startingAfter` (a
  period such as `2026-10`).
- `GET /v1/statements/{period}` returns one statement:

```json
{"object": "statement", "period": "2026-10", "livemode": true, "currency": "AUD", "timeZone": "Australia/Sydney",
 "periodStart": "2026-09-30T14:00:00.000Z", "periodEnd": "2026-10-31T13:00:00.000Z", "status": "issued",
 "deliveryCount": 42, "adjustmentCount": 1, "lineCount": 43,
 "totals": {"chargedCents": 68082, "gstCents": 6189, "refundedCents": 3121, "refundedGstCents": 284,
            "netCents": 64961, "netGstCents": 5905},
 "generatedAt": "2026-11-01T16:30:12.000Z", "notice": "Statement only. …"}
```

- `GET /v1/statements/{period}/lines` returns its lines in order. Query: `limit` (1–500, default 100) and
  `startingAfter` (a line number). Each line has `lineNumber`, `kind`, `deliveryId`, `externalReference`, `created`,
  `status`, `vehicle`, `chargedCents`, `gstCents`, `refundedCents`, `refundedGstCents`, `netCents`, `receipt`
  (`issued` or `not_issued`) and `receiptNumber` (the receipt that is the tax invoice for that delivery, when issued).
- Return charges appear separately as `return_delivery`; later refunds use `return_refund_adjustment`.
  Return lines show `receipt: not_issued` until a separate receipt is available; the statement remains a summary.
- `kind` is `delivery` for a delivery booked in that month, or `refund_adjustment` for a refund made after the
  delivery appeared on an earlier statement (up to three months back). Adjustment lines carry `originalPeriod` and
  only the newly refunded amount. Statements are never changed once issued.
- Test keys have no statements: the list is empty and a period returns `404 statement_not_found`.

## Webhooks

Register webhook endpoints in the MeowX Business portal: developers and owners add test endpoints, and only owners
add live ones. The signing secret (`whsec_…`) is shown once, to you only. Events: `delivery.created`, `delivery.rider_assigned`, `delivery.picked_up`, `delivery.delivered`,
`delivery.cancelled`, `delivery.failed`, and `statement.ready` (live only; `data.object` is the statement summary).

```json
{"id": "evt_9c2e…", "object": "event", "type": "delivery.picked_up", "apiVersion": "2026-11-04",
 "created": "2026-11-04T01:05:00.000Z", "livemode": true,
 "data": {"object": {"id": "dlv_live_…", "object": "delivery", "status": "picked_up", "…": "…"}}}
```

Headers: `MeowX-Signature: t=<unix seconds>,v1=<hex>`, `MeowX-Event-Id`, `MeowX-Event-Type`, `MeowX-Delivery-Attempt`.
Live status events usually arrive within about a minute of the change.

Verify every request before trusting it:

1. Take the raw request body bytes exactly as received.
2. Compute `HMAC-SHA256(secret, "<t>.<raw body>")` as lowercase hex.
3. Compare with `v1` in constant time, and reject if `t` is more than 5 minutes from your clock.

```js
const crypto = require("crypto");
function verifyMeowX(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const t = Number(parts.t);
  if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(parts.v1 || "", "hex");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}
```

```python
import hmac, hashlib, time
def verify_meowx(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    t = int(parts.get("t", "0"))
    if abs(time.time() - t) > 300:
        return False
    expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))
```

Respond with any `2xx` within 10 seconds; do slow work asynchronously. Other responses, timeouts and redirects are
retried after about 1 minute, 5 minutes, 30 minutes, 2, 6, 12 and 24 hours (8 attempts). Events can arrive more than
once or out of order: deduplicate by `MeowX-Event-Id` and use the delivery's `status` and `updatedAt`. An endpoint that
keeps failing is disabled; MeowX operations can re-enable it and replay failed events. Webhook URLs must be `https://`
on the default port with a public DNS name.

## Going live checklist

1. Your integration passes in test mode, including retries with the same `Idempotency-Key` and webhook verification.
2. Your account owner has a MeowX Go account with the business card saved, and has signed the MeowX business
   agreement allowing per-delivery charges.
3. MeowX enables live mode for your business; your account owner (invited by MeowX, see above) then creates the live
   key and registers the live webhook endpoint in the MeowX Business portal. The portal also lists your deliveries
   (status, amount and receipt number) and your monthly statements.
4. Place one low-value live delivery and cancel it before a rider accepts to confirm the full flow.

## Tracking links and recipient texts

Every live delivery comes with `trackingUrl`: a page on meowx.com.au that anyone with the link can open without an
app. It shows the delivery's progress, the suburbs it travels between, your business name, the rider's first name and
vehicle, where the rider is while the item is on its way, the estimated arrival time and, after delivery, the delivery
photo. It never shows names, phone numbers or street addresses. The page stops showing details 30 days after the
delivery ends.

Unless you turn it off, MeowX texts the recipient at `dropoff.phone` (Australian mobiles only) twice: when the rider
has the item, with the link, and when it has been delivered. The texts name your business. To send your own messages
instead, create the delivery with:

```json
"notifications": {"recipientSms": false}
```

You can still give your customer `trackingUrl` yourself, for example in your own app, emails or mini program. The
delivery object returns your choice in `notifications.recipientSms`.

By giving MeowX the recipient's mobile number you confirm that the recipient expects to be contacted about this
delivery.

In test mode `trackingUrl` points to a demo page that plays a sample delivery, and no texts are sent.
