Send pickup orders to Aillo

This API sends expected orders to one branch. It does not create an arrival request or send a team text by itself.

Endpoint and authentication

POST /api/v1/expected-pickups

Authorization: Bearer ak_YOUR_PICKUP_KEY
Content-Type: application/json

Create the branch key in API & webhooks. Copy it once and keep it on your server, never in public browser code. A revoked key returns 401 immediately. The branch is taken from the key; business IDs and other unknown body fields are ignored.

Order fields

Field	Required	Rules
`order_number`	Required	String, trimmed, 1–40 characters. Keep leading zeroes.
`customer_name`	Required for upsert	String, trimmed, 1–80 characters. Optional for cancel; if supplied, maximum 80.
`phone`	Optional	NANP phone string, maximum 40 characters. Missing, null or empty means no phone. An unusable supplied value is ignored, not rejected.
`pickup_date`	Optional	YYYY-MM-DD. Missing, null or empty defaults to today in business_settings.timezone (Toronto fallback).
`action`	Optional	"upsert" (default) or "cancel".

Phone formats and warnings

(263) 555-0101, 263-555-0101, +1 263 555 0101 → +12635550101

Non-digits are removed. Ten digits get +1; eleven digits starting with 1 get +. The area code must start with 2–9. Other values, including strings over 40 characters, are saved as null. For an upsert with an unusable supplied phone, the order still saves with HTTP 200 and phone_ignored. No phone means no caller-ID matching for this order.

{"ok":true,"upserted":1,"cancelled":0,"orders":[{"order_number":"1001","pickup_date":"2026-10-13","warnings":["phone_ignored"]}]}

The orders array is included only when at least one item has a warning. It then lists every processed item with order_number, pickup_date and warnings (empty for unaffected items). Missing/null/empty phones and cancel actions do not produce this warning.

Batch, update and cancel

Send one JSON object or a non-empty array of at most 500 objects. All items are validated before one database transaction; one invalid item rejects the whole batch.

upsert inserts or updates the same branch + order_number + pickup_date, without duplication. Resend the complete current customer_name and phone; omitting phone on an update clears the stored phone. cancel deletes that branch's order for that exact date; customer_name and phone are not needed.

{"order_number":"1001","action":"cancel"}

Date window, inclusive: today minus 1 day through today plus 14 days, in the store's configured time zone. Success is HTTP 200 with ok, upserted and cancelled counts; a cancel of a missing order reports cancelled: 0.

Limits and errors

Body limit: 256000 for declared Content-Length (bytes) and decoded JavaScript text length. JSON content-type values beginning application/json are accepted, including charset parameters.

400 — invalid_json, too_many_items, invalid_request: validation errors have a fields array with paths such as items[0].customer_name; nothing is saved.
401 — unauthorized: missing/wrong Bearer key or revoked key.
413 — payload_too_large (maxBytes).
415 — invalid_content_type.
500 — server_error: database write failed.

Example: one order for today

curl -X POST 'https://app.aillo.ca/api/v1/expected-pickups' \
  -H 'Authorization: Bearer ak_YOUR_PICKUP_KEY' \
  -H 'Content-Type: application/json' \
  --data '{"order_number":"1001","customer_name":"Test","phone":"(263) 555-0101"}'

Replace the example host and placeholder key with your Aillo address and branch key.