API documentation

The shop

• GET/public/shops/{slug}Public, no key

The shop's name, what it takes online, its opening hours and today's collection times. Use it to build the first screen of a booking or ordering form.

Opening hours are keyed by ISO weekday, "1" Monday to "7" Sunday. A closing time before the opening time runs past midnight. A day left out is closed.

curl https://api.unitedpos.co.uk/public/shops/example-kitchen

{
  "name": "Example Kitchen",
  "ordering": true,
  "booking": true,
  "open_now": true,
  "hours": {
    "1": { "open": "12:00", "close": "22:00" },
    "5": { "open": "12:00", "close": "02:00" }
  },
  "prep_minutes": 20,
  "asap": true,
  "pickup_times": ["18:45", "19:00", "19:15"],
  "booking_max_party": 8,
  "booking_days_ahead": 30,
  "today": "2026-10-27"
}

Refusals

• 404"No shop at this address": no shop has that slug, or it takes neither orders nor bookings online.

Free booking times

• GET/public/shops/{slug}/booking-timesPublic, no key
• GET/api/v1/booking-timesAPI key

The times on one day that still have room for a party. Times are every 15 minutes from the opening (or from now plus the shop's notice) to an hour before the close, on the shop's own clock.

The web books only part of the room: a time is offered while the bookings that overlap it, from every source, leave room for the party within the seats the shop gives the web. A day outside the booking window, or a closed day, returns an empty list.

Query

curl "https://api.unitedpos.co.uk/api/v1/booking-times?date=2026-10-30&party=2" \
  -H "Authorization: Bearer up_live_YOUR_KEY"

{
  "date": "2026-10-30",
  "times": ["18:00", "18:15", "18:30", "20:45", "21:00"]
}

Refusals

• 400date or party is missing or not valid, or the party is outside 1 to booking_max_party: "Book for 1 to 8 online; call the shop for more".
• 404"This shop does not take bookings here": table bookings are switched off.

Book a table

• POST/public/shops/{slug}/bookingsPublic, no key
• POST/api/v1/bookingsAPI key

A confirmed booking, if the time still has room. It goes straight into the shop's Reservations, marked as from the web (public route) or from the API (key route), and holds its seats for the shop's booking length.

Ask for the free times first and send one of them. Two bookings at the same moment cannot both take the last seats: the second is refused with 409.

JSON body

curl -X POST https://api.unitedpos.co.uk/api/v1/bookings \
  -H "Authorization: Bearer up_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"date": "2026-10-30", "time": "19:00", "party": 2, "name": "Ann Smith", "phone": "07700 900123"}'

{
  "id": "7f1c2a4e-3b5d-4c8e-9a61-0d2f4b6e8a10",
  "shop": "Example Kitchen",
  "date": "2026-10-30",
  "time": "19:00",
  "party": 2
}

Refusals

• 400A field is missing or not valid, for example "Give a phone number the shop can call", "Give a name, up to 60 characters", "The email address is not valid", "A note is up to 200 characters" or "Choose a time".
• 404"This shop does not take bookings here".
• 409"19:00 is no longer free for 2. Choose another time.", or "This phone number already has a booking that day. Please call the shop to change it." (one booking per phone number per trading day).
• 429Public route only: more than 5 bookings from one caller in 10 minutes, more than 30 web bookings at the shop in an hour, or more covers from one caller in 12 hours than the web may take (the larger of the largest party and half the web seats).

List bookings

• GET/api/v1/bookingsAPI key

The shop's bookings from every source (till, web, API) between two dates on the shop's clock, both included, in time order. Key only.

Left out, the range is today and the 30 days after. A range is at most 92 days, and a list returns at most 500 bookings.

Query

curl "https://api.unitedpos.co.uk/api/v1/bookings?from=2026-10-27&to=2026-11-03" \
  -H "Authorization: Bearer up_live_YOUR_KEY"

{
  "from": "2026-10-27",
  "to": "2026-11-26",
  "bookings": [
    {
      "date": "2026-10-30",
      "time": "19:00",
      "id": "7f1c2a4e-3b5d-4c8e-9a61-0d2f4b6e8a10",
      "name": "Ann Smith",
      "phone": "07700 900123",
      "email": null,
      "party": 2,
      "reserved_at": "2026-10-30T19:00:00Z",
      "duration_minutes": 90,
      "status": "confirmed",
      "source": "api",
      "notes": null
    }
  ]
}

Refusals

• 400"Give from and to as dates, from before to, at most 92 days apart".
• 404"This shop does not take bookings here".

One booking

• GET/api/v1/bookings/{id}API key

One of the shop's own bookings by its id, in the same shape as an entry in the list. status is confirmed, seated, completed, cancelled or no_show. Key only.

curl https://api.unitedpos.co.uk/api/v1/bookings/7f1c2a4e-3b5d-4c8e-9a61-0d2f4b6e8a10 \
  -H "Authorization: Bearer up_live_YOUR_KEY"

{
  "date": "2026-10-30",
  "time": "19:00",
  "id": "7f1c2a4e-3b5d-4c8e-9a61-0d2f4b6e8a10",
  "name": "Ann Smith",
  "phone": "07700 900123",
  "email": null,
  "party": 2,
  "reserved_at": "2026-10-30T19:00:00Z",
  "duration_minutes": 90,
  "status": "seated",
  "source": "api",
  "notes": null
}

Refusals

• 404"No such booking" (including another shop's), or bookings are switched off.

Menu

• GET/public/shops/{slug}/menuPublic, no key
• GET/api/v1/menuAPI key

Today's take-away menu: the dishes on sale today, by category in menu order, at the take-away price with VAT included and any offer on now already taken off. Dishes sold out for today, and dishes priced at the till, are left out.

A category with available_from and available_until is on sale only between those times. A dish with sizes is priced by the size chosen. groups are the choices a dish offers, with the rules for how many to pick.

curl https://api.unitedpos.co.uk/api/v1/menu \
  -H "Authorization: Bearer up_live_YOUR_KEY"

{
  "categories": [
    {
      "id": "0b8e6f52-2a1d-4f7b-8c39-5d1e7a9c3b24",
      "name": "Mains",
      "available_from": null,
      "available_until": null,
      "products": [
        {
          "id": "c3a1e9d7-5b2f-4e8a-9c61-7d0f2b4e6a18",
          "name": "Chicken wrap",
          "description": "Grilled chicken, salad and garlic sauce",
          "image_url": null,
          "price": "8.50",
          "was": null,
          "offer": null,
          "allergens": ["gluten", "milk"],
          "sizes": [
            { "id": "a7d2c4e6-1b3f-4a5c-8e7d-9f0b1c2d3e4f", "name": "Large", "price": "10.50", "was": null }
          ],
          "groups": [
            {
              "id": "e5f7a9c1-3d2b-4f6e-8a0c-1b3d5f7a9c2e",
              "tenant_id": "9d4b2f6a-8c1e-4a3d-b5f7-0e2c4a6b8d1f",
              "name": "Sauce",
              "min_select": 1,
              "max_select": 1,
              "max_per_option": 1,
              "sort_order": 0,
              "required": true,
              "multi_select": false,
              "options": [
                {
                  "id": "f1e2d3c4-b5a6-4978-8a9b-0c1d2e3f4a5b",
                  "name": "Chilli",
                  "price_adjustment": "0.00",
                  "sort_order": 0,
                  "is_default": false,
                  "is_active": true
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

Refusals

• 404"This shop does not take orders here": collection orders are switched off (or, public route, no shop at this address).

Place a collection order

• POST/public/shops/{slug}/ordersPublic, no key
• POST/api/v1/ordersAPI key

An order to collect today, paid at the counter. Nothing here takes money. The order rings on the shop's tills as a web order and goes to the kitchen only once someone at a till accepts it; if nobody answers within 10 minutes it lapses.

Send dishes and choices, never amounts: the server prices every line from the shop's own menu at the take-away price. Send the same key again (for example after a timeout) and you get the first order back with 200, never a second order.

JSON body

curl -X POST https://api.unitedpos.co.uk/api/v1/orders \
  -H "Authorization: Bearer up_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "product_id": "c3a1e9d7-5b2f-4e8a-9c61-7d0f2b4e6a18",
        "quantity": 2,
        "modifiers": [{ "option_id": "f1e2d3c4-b5a6-4978-8a9b-0c1d2e3f4a5b" }]
      }
    ],
    "name": "Ann Smith",
    "phone": "07700 900123",
    "pickup": "asap",
    "key": "2b6f0d84-91c3-4e57-a8d2-6c0e4f1b9a37"
  }'

{
  "token": "4f0c9a2e7b1d4c6a8e3f5b7d9a1c2e4f6b8d0a2c4e6f8a1b3d5f7a9c1e3b5d7f",
  "order_number": "261027-0042",
  "total": "19.00",
  "collect_at": "19:15"
}

Refusals

• 400A field is missing or not valid: lines, quantities, a dish, size or choice that is not on the menu, choices outside a group's rules, "Choose a collection time", or "Orders over £250 are taken by phone. Please call the shop." (subtotal).
• 404"This shop does not take orders here".
• 409"Chicken wrap is not available at 18:30", a size or choice switched off, "The shop is closed now. Choose a later time.", "18:30 is no longer available. Choose another time.", or "You already have orders on the way. Please collect them, or call the shop." (3 open web orders per phone number).
• 429More than 5 orders for one phone number at the shop in an hour (both routes), or, on the public route, more than 5 orders from one caller in 10 minutes.
• 503"The shop is very busy right now. Please call to order.": 20 web orders are already waiting for the till.

Follow an order

• GET/public/orders/{token}Public, no key

Where a collection order is, by the token its placing returned. The token is the only key, so give it only to the customer.

status is waiting (for the shop to confirm), confirmed, ready, collected, declined, cancelled (by the shop, after it was confirmed) or lapsed (nobody answered in time). reason is the shop's reason when it declined.

curl https://api.unitedpos.co.uk/public/orders/4f0c9a2e7b1d4c6a8e3f5b7d9a1c2e4f6b8d0a2c4e6f8a1b3d5f7a9c1e3b5d7f

{
  "shop": "Example Kitchen",
  "order_number": "261027-0042",
  "status": "confirmed",
  "reason": null,
  "collect_at": "19:15",
  "total": "19.00",
  "items": [
    { "name": "Chicken wrap", "quantity": 2, "total": "17.00" },
    { "name": "Chips", "quantity": 1, "total": "2.00" }
  ]
}

Refusals

• 404"No order at this address".
• 429More than 120 requests from one caller in a minute.

AppointmentsComing soon

Appointments for services are booked by staff on the till today. There is no public route for them yet: an appointment booking API is coming soon.