Developers

Let an AI assistant manage your bookings

The AIPickUp4U merchant API lets an AI assistant you choose, such as Meta Muse, read your shop’s bookings and, if you allow it, book, move and cancel them. This page is the whole documentation.

Last updated 29 September 2026

What you can do

16 operations in four groups, listed below. Reading is always on for a key. Everything that changes something is a separate permission the owner ticks when creating the key, and the assistant only ever gets the permissions on that key.

Get a key

On the Pro plan, open the merchant console, go to Settings, then API access, then New key. Name it, tick the permissions, create it. The key is shown once, so copy it then; we store only a one-way hash. Revoke it any time from the same card and anything using it stops working immediately. A shop can hold up to 10 active keys.

Access requirements

You need an AIPickUp4U account on the Pro plan, for a business in the United States or Canada. API access is not available to dental practices or medical clinics, because bookings there contain patient information. Each key is limited to 120 read requests and 30 write requests per minute.

Times and dates are the shop’s own

Every date and time you send or receive is wall-clock time in the shop’s timezone. Do not convert it, and do not work out “today” yourself: call getConnectorMe and use its timezone and today fields. The one exception is order pickup_at, an ISO 8601 timestamp in UTC.

The sixteen operations

Read

Every key has this scope. Nothing here contacts a customer or changes anything.

getConnectorMe GET /connector/me
Who am I: shop, timezone, today, hours, this key’s scopes. Read-only.
listBookings GET /bookings
List bookings by date or status. Read-only. Does not contact the customer.
getBooking GET /bookings/{booking_id}
Get one booking. Read-only.
getAvailability GET /availability
Open times for a date and service. Read-only. Does not hold the slot.
getStats GET /stats
Today’s numbers. Read-only.
listServices GET /services
Services the shop offers. Read-only.
listResources GET /resources
Staff, tables or rooms. Read-only.
getMenu GET /menu
The menu (food businesses). Read-only.
listOrders GET /orders
Orders for a date. Read-only.
listBlockedSlots GET /blocked-slots
Windows closed to new bookings. Read-only.

Bookings: bookings:write

These text your customers. The owner turns this scope on per key.

createBooking POST /bookings
Book a customer in. Creates a booking and texts the customer a confirmation.
rescheduleBooking POST /bookings/{booking_id}/reschedule
Move a booking. Moves the booking and texts the customer the new time. The assistant should ask the owner to confirm first.
cancelBooking DELETE /bookings/{booking_id}
Cancel a booking. Cancels the booking and texts the customer. Cannot be undone. The assistant should ask the owner to confirm first.

Orders: orders:write

For food businesses that take orders.

updateOrderStatus PATCH /orders/{order_id}
Change an order’s status. Changes the order status. Cancelling texts the customer.

Closing times: config:write

Off by default. Turn it on only if the assistant needs to close windows.

blockSlot POST /blocked-slots
Stop new bookings in a window. Stops new bookings in that window; existing bookings stay. The assistant should ask the owner to confirm first.
unblockSlot DELETE /blocked-slots/{block_id}
Reopen a closed window. Reopens the window for new bookings.

Connecting

Base URL: https://app.aipickup4u.com/api/v1
Authentication: Authorization: Bearer ak_live_…
Content type: application/json
Idempotency: Idempotency-Key: <unique string, up to 128 characters> on the five write operations

Send an Idempotency-Key with every write (createBooking, rescheduleBooking, cancelBooking, blockSlot, updateOrderStatus). Repeat the same key with the same request and you get the original result back, and the customer is not texted a second time. Reuse the key for a different request and it is rejected with 422 idempotency_key_reused. Use a fresh key for each new action.

Three examples

Set KEY to your key. The ids and the phone number below are made up; the booking example really does text the number you give it, so use your own when you try it.

Tomorrow’s bookings

Ask the shop for its today first, add one day, then list that date.

curl -s -H "Authorization: Bearer $KEY" \
  https://app.aipickup4u.com/api/v1/connector/me

curl -s -H "Authorization: Bearer $KEY" \
  "https://app.aipickup4u.com/api/v1/bookings?date=2026-10-01"

Book a customer in

Find a free time with getAvailability, then book it. resource_id comes from the slot, service_id from listServices.

curl -s -X POST https://app.aipickup4u.com/api/v1/bookings \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2a90-3b1e-4c7d-9a55-0d2c8e4b7a11" \
  -d '{
    "resource_id": "0b7f0c0e-6a55-4c1e-8d3a-2f4e9a1b7c30",
    "service_id": "5d2a9c41-1e7b-4f08-b6a3-9c0d3e8f2a17",
    "booking_date": "2026-10-01",
    "start_time": "14:00",
    "guest_name": "Lisa Chen",
    "guest_phone": "+14165550188",
    "party_size": 1
  }'

Cancel a booking

The customer is texted a cancellation, and it cannot be undone.

curl -s -X DELETE https://app.aipickup4u.com/api/v1/bookings/9e3b7d52-4a10-4e6c-a1f8-7b2c5d0e6f43 \
  -H "Authorization: Bearer $KEY" \
  -H "Idempotency-Key: c81d4e07-92aa-4b35-8f60-1e5a7d9b3c22"

Errors

Every error on a request made with an API key is JSON: {"error": {"code": "...", "message": "..."}}. Branch on code, which is stable; message is for people.

Status	Code	Meaning
401	`invalid_key`	The key is not recognised.
401	`key_revoked`	The key has been revoked.
403	`plan_required`	The shop is not on the Pro plan.
403	`trade_not_supported`	API access is not available for this type of business.
403	`scope_missing`	The key lacks the permission this operation needs, or the endpoint is not one of the sixteen above.
429	`rate_limited`	Too many requests. Wait for the Retry-After header before retrying.
503	`connector_disabled`	API access is temporarily switched off.
422	`validation_error`	The request body or query is malformed, or the change is not allowed (for example an order status move that is not a forward move). The message names the fields when it can.
422	`idempotency_key_reused`	That Idempotency-Key was already used for a different request.
409	`idempotency_conflict`	A request with the same Idempotency-Key is still running. Retry shortly.
404	`not_found`	The id does not exist in this shop.
409	`conflict`	The requested time is taken.
400	`bad_time, outside_hours, slot_blocked, skill_mismatch, capacity_mismatch, contact_required, too_soon, out_of_service_area`	A booking rule failed; the code names the rule. Which ones apply depends on the type of business.

Machine-readable spec and status

The OpenAPI 3 spec for exactly these sixteen operations is public and needs no key. Every operation carries a plain-English description of its side effects, so an assistant can tell a read from a text to a customer.

OpenAPI spec: https://app.aipickup4u.com/api/v1/connector/openapi.json

Service health: https://app.aipickup4u.com/health. A plain GET that returns 200 when the service is up. We do not offer an uptime guarantee; see the terms.

Connect to Meta Muse

In AIPickUp4U, create a key under Settings, API access. Tick only the permissions you want Muse to have, and copy the key.
In Muse, open Connectors and choose Add custom connector.
Paste the OpenAPI spec address above and the key. Then ask Muse about tomorrow’s bookings.