For developers

OneBuzz API

Make orders from a kiosk, another POS or a delivery tool, buzz the customer's phone when the food is ready, and read the menu, tables and sales of a OneBuzz restaurant.

Base addresshttps://onebuzzfood.com/api/v1 OpenAPI file

Quick start

  1. Get a key. The restaurant owner opens Settings → API & connected apps in OneBuzz, makes a key and gives it to you. It starts with ob_live_ and is shown once.
  2. Check it.
    curl https://onebuzzfood.com/api/v1/me -H "Authorization: Bearer $ONEBUZZ_KEY"
  3. Make an order. Item ids come from GET /menu. Prices always come from the OneBuzz menu, never from your request.
    curl -X POST https://onebuzzfood.com/api/v1/orders \
      -H "Authorization: Bearer $ONEBUZZ_KEY" \
      -H "Content-Type: application/json" \
      -d '{"external_id":"kiosk-2026-000187","customer_name":"Aman","payment_mode":"CARD","items":[{"item_id":12,"qty":2,"variant":"Large"},{"item_id":31,"qty":1}]}'
  4. Give the customer the buzzer. Show order.buzzer.join_url as a QR code or send it to their phone.
  5. Buzz them. When the food is ready:
    curl -X POST https://onebuzzfood.com/api/v1/orders/48213/ready -H "Authorization: Bearer $ONEBUZZ_KEY"

Every answer is JSON: {"success": true, "data": {…}}, or {"success": false, "error": {"code": "…", "message": "…"}} with a matching HTTP status. Times are UTC in ISO 8601. Money is a number in the restaurant's currency.

Keys & permissions

Send the key in the Authorization: Bearer header (or X-API-Key) over https. Call the API from your server, never from a web page or a phone app, because anyone could read the key there. A key works for one restaurant and can be tied to one outlet. The owner can remove it at any time.

PermissionWhat it allows
orders:readSee orders and buzzers
orders:writeMake orders and buzzers, mark them preparing, ready, delivered or cancelled
menu:readSee the menu
menu:writeMark menu items available or sold out
sales:readSee sales totals
tables:readSee tables and what is running on them
staff:readSee the team and their login hours
webhooks:writeAdd and remove webhooks

Restaurant

Who the key belongs to and its outlets.

GET/api/v1/me

This key. The restaurant, what the key may do and its outlets. A good first call to check a key.

Works with any key

Example
curl https://onebuzzfood.com/api/v1/me \
  -H "Authorization: Bearer $ONEBUZZ_KEY"
{
  "success": true,
  "data": {
    "restaurant": {
      "id": 7,
      "name": "Pizza Point",
      "currency": "$",
      "tax_label": "GST",
      "tax_percent": 15,
      "tax_included": true
    },
    "key": {
      "id": 4,
      "name": "Kiosk",
      "scopes": [
        "orders:read",
        "orders:write",
        "menu:read"
      ],
      "location_id": null,
      "created_at": "2026-11-12T09:00:00Z"
    },
    "locations": [
      {
        "id": 3,
        "name": "Main counter",
        "address": null,
        "city": "Auckland",
        "country": "NZ",
        "timezone": "Pacific/Auckland",
        "pickup_point": "Counter 1",
        "buzzer_on_every_order": true
      }
    ],
    "rate_limit": {
      "requests_per_minute": 120
    }
  }
}

GET/api/v1/locations

Outlets. The outlets this key can use.

Works with any key

Example
curl https://onebuzzfood.com/api/v1/locations \
  -H "Authorization: Bearer $ONEBUZZ_KEY"
{
  "success": true,
  "data": {
    "locations": [
      {
        "id": 3,
        "name": "Main counter",
        "address": null,
        "city": "Auckland",
        "country": "NZ",
        "timezone": "Pacific/Auckland",
        "pickup_point": "Counter 1",
        "buzzer_on_every_order": true
      }
    ]
  }
}

Orders & buzzers

An order is a buzzer, a bill, or both. Its status goes WAITING → PREPARING → READY → DELIVERED, or CANCELLED.

GET/api/v1/orders

List orders. Newest first. Without dates you get today. status=active gives every order still running, whatever the day.

Needs orders:read

Query

location_idintegerThe outlet. Needed only when the restaurant has more than one and the key is not tied to one.
statusstringactive, waiting, preparing, ready, delivered or cancelled.
fromdateFirst day, YYYY-MM-DD, in the outlet's time zone.
todateLast day, YYYY-MM-DD. At most 92 days in one call.
external_idstringFind the order you made with this external_id.
limitinteger1 to 100. Default 50.
before_idintegerFor the next page: the next_before_id of the last answer.
Example
curl https://onebuzzfood.com/api/v1/orders \
  -H "Authorization: Bearer $ONEBUZZ_KEY"
{
  "success": true,
  "data": {
    "orders": [
      {
        "id": 48213,
        "code": "104",
        "status": "WAITING",
        "has_buzzer": true,
        "location_id": 3,
        "external_id": "kiosk-2026-000187",
        "customer_name": "Aman",
        "notes": "2× Margherita (Large), 1× Coke",
        "order_type": "TAKEAWAY",
        "table_no": null,
        "customer_phone": null,
        "buzz_count": 0,
        "customer": {
          "connected": false,
          "response": "NONE",
          "response_at": null
        },
        "bill": {
          "id": 9917,
          "bill_no": 2451,
          "currency": "$",
          "subtotal": 52.5,
          "discount": 0,
          "tax_percent": 15,
          "tax_amount": 6.85,
          "round_off": 0,
          "total": 52.5,
          "payment_mode": "CARD",
          "paid": 52.5,
          "due": 0,
          "pay_state": "PAID",
          "items": [
            {
              "item_id": 12,
              "name": "Margherita",
              "variant": "Large",
              "type": "VEG",
              "qty": 2,
              "unit_price": 24,
              "line_total": 48,
              "note": null,
              "addons": []
            },
            {
              "item_id": 31,
              "name": "Coke",
              "variant": null,
              "type": "VEG",
              "qty": 1,
              "unit_price": 4.5,
              "line_total": 4.5,
              "note": null,
              "addons": []
            }
          ]
        },
        "created_at": "2026-11-30T07:41:12Z",
        "preparing_at": null,
        "ready_at": null,
        "delivered_at": null,
        "cancelled_at": null,
        "updated_at": "2026-11-30T07:41:12Z",
        "buzzer": {
          "join_url": "https://onebuzzfood.com/customer/join.php?t=…",
          "join_code": "482913"
        }
      }
    ],
    "has_more": false,
    "next_before_id": null,
    "filters": {
      "status": null,
      "from": "2026-11-30",
      "to": "2026-11-30",
      "limit": 50
    }
  }
}

GET/api/v1/orders/{id}

One order. The order with its bill, items and, while the buzzer is active, the customer's buzzer link.

Needs orders:read

Example
curl https://onebuzzfood.com/api/v1/orders/48213 \
  -H "Authorization: Bearer $ONEBUZZ_KEY"
{
  "success": true,
  "data": {
    "order": {
      "id": 48213,
      "code": "104",
      "status": "WAITING",
      "has_buzzer": true,
      "location_id": 3,
      "external_id": "kiosk-2026-000187",
      "customer_name": "Aman",
      "notes": "2× Margherita (Large), 1× Coke",
      "order_type": "TAKEAWAY",
      "table_no": null,
      "customer_phone": null,
      "buzz_count": 0,
      "customer": {
        "connected": false,
        "response": "NONE",
        "response_at": null
      },
      "bill": {
        "id": 9917,
        "bill_no": 2451,
        "currency": "$",
        "subtotal": 52.5,
        "discount": 0,
        "tax_percent": 15,
        "tax_amount": 6.85,
        "round_off": 0,
        "total": 52.5,
        "payment_mode": "CARD",
        "paid": 52.5,
        "due": 0,
        "pay_state": "PAID",
        "items": [
          {
            "item_id": 12,
            "name": "Margherita",
            "variant": "Large",
            "type": "VEG",
            "qty": 2,
            "unit_price": 24,
            "line_total": 48,
            "note": null,
            "addons": []
          },
          {
            "item_id": 31,
            "name": "Coke",
            "variant": null,
            "type": "VEG",
            "qty": 1,
            "unit_price": 4.5,
            "line_total": 4.5,
            "note": null,
            "addons": []
          }
        ]
      },
      "created_at": "2026-11-30T07:41:12Z",
      "preparing_at": null,
      "ready_at": null,
      "delivered_at": null,
      "cancelled_at": null,
      "updated_at": "2026-11-30T07:41:12Z",
      "buzzer": {
        "join_url": "https://onebuzzfood.com/customer/join.php?t=…",
        "join_code": "482913"
      }
    }
  }
}

POST/api/v1/orders

Make an order. With "items" it makes a bill (prices always come from the OneBuzz menu) and, unless the outlet has buzzers off, a buzzer. Without "items" it makes a buzzer only. Show buzzer.join_url as a QR or send it to the customer: their phone rings when the order is ready. Send your own order id as external_id (or an Idempotency-Key header) and a repeated call returns the same order with "duplicate": true.

Needs orders:write

Body (JSON)

location_idintegerThe outlet. Needed only when the restaurant has more than one and the key is not tied to one.
itemsarrayThe lines: {"item_id", "qty", "variant" (size name, when the item has sizes), "note", "addons": [{"g": add-on group id, "n": option name}]}.
external_idstringYour own id for this order, at most 80 characters. Makes the call safe to repeat.
customer_namestringShown on the Live board and the bill.
customer_phonestringDigits only. Also used for loyalty points when the restaurant has them on.
order_typestringTAKEAWAY (default), DINE_IN or DELIVERY.
table_nostringFor DINE_IN.
payment_modestringUNPAID (default: the counter collects), CASH or CARD when you already took the money.
discountnumberAn amount taken off the bill.
buzzerbooleantrue or false to decide it yourself; leave it out to follow the outlet's setting.
notesstringOnly for a buzzer without items.
Example
curl -X POST https://onebuzzfood.com/api/v1/orders \
  -H "Authorization: Bearer $ONEBUZZ_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_id":"kiosk-2026-000187","customer_name":"Aman","payment_mode":"CARD","items":[{"item_id":12,"qty":2,"variant":"Large"},{"item_id":31,"qty":1}]}'
{
  "success": true,
  "data": {
    "order": {
      "id": 48213,
      "code": "104",
      "status": "WAITING",
      "has_buzzer": true,
      "location_id": 3,
      "external_id": "kiosk-2026-000187",
      "customer_name": "Aman",
      "notes": "2× Margherita (Large), 1× Coke",
      "order_type": "TAKEAWAY",
      "table_no": null,
      "customer_phone": null,
      "buzz_count": 0,
      "customer": {
        "connected": false,
        "response": "NONE",
        "response_at": null
      },
      "bill": {
        "id": 9917,
        "bill_no": 2451,
        "currency": "$",
        "subtotal": 52.5,
        "discount": 0,
        "tax_percent": 15,
        "tax_amount": 6.85,
        "round_off": 0,
        "total": 52.5,
        "payment_mode": "CARD",
        "paid": 52.5,
        "due": 0,
        "pay_state": "PAID",
        "items": [
          {
            "item_id": 12,
            "name": "Margherita",
            "variant": "Large",
            "type": "VEG",
            "qty": 2,
            "unit_price": 24,
            "line_total": 48,
            "note": null,
            "addons": []
          },
          {
            "item_id": 31,
            "name": "Coke",
            "variant": null,
            "type": "VEG",
            "qty": 1,
            "unit_price": 4.5,
            "line_total": 4.5,
            "note": null,
            "addons": []
          }
        ]
      },
      "created_at": "2026-11-30T07:41:12Z",
      "preparing_at": null,
      "ready_at": null,
      "delivered_at": null,
      "cancelled_at": null,
      "updated_at": "2026-11-30T07:41:12Z",
      "buzzer": {
        "join_url": "https://onebuzzfood.com/customer/join.php?t=…",
        "join_code": "482913"
      }
    },
    "duplicate": false
  }
}

POST/api/v1/orders/{id}/preparing

Mark preparing. The kitchen started. Only a WAITING order can move here.

Needs orders:write

Example
curl -X POST https://onebuzzfood.com/api/v1/orders/48213/preparing \
  -H "Authorization: Bearer $ONEBUZZ_KEY"
{
  "success": true,
  "data": {
    "order": {
      "id": 48213,
      "code": "104",
      "status": "PREPARING",
      "has_buzzer": true,
      "location_id": 3,
      "external_id": "kiosk-2026-000187",
      "customer_name": "Aman",
      "notes": "2× Margherita (Large), 1× Coke",
      "order_type": "TAKEAWAY",
      "table_no": null,
      "customer_phone": null,
      "buzz_count": 0,
      "customer": {
        "connected": false,
        "response": "NONE",
        "response_at": null
      },
      "bill": {
        "id": 9917,
        "bill_no": 2451,
        "currency": "$",
        "subtotal": 52.5,
        "discount": 0,
        "tax_percent": 15,
        "tax_amount": 6.85,
        "round_off": 0,
        "total": 52.5,
        "payment_mode": "CARD",
        "paid": 52.5,
        "due": 0,
        "pay_state": "PAID",
        "items": [
          {
            "item_id": 12,
            "name": "Margherita",
            "variant": "Large",
            "type": "VEG",
            "qty": 2,
            "unit_price": 24,
            "line_total": 48,
            "note": null,
            "addons": []
          },
          {
            "item_id": 31,
            "name": "Coke",
            "variant": null,
            "type": "VEG",
            "qty": 1,
            "unit_price": 4.5,
            "line_total": 4.5,
            "note": null,
            "addons": []
          }
        ]
      },
      "created_at": "2026-11-30T07:41:12Z",
      "preparing_at": "2026-11-30T07:43:00Z",
      "ready_at": null,
      "delivered_at": null,
      "cancelled_at": null,
      "updated_at": "2026-11-30T07:41:12Z",
      "buzzer": {
        "join_url": "https://onebuzzfood.com/customer/join.php?t=…",
        "join_code": "482913"
      }
    },
    "changed": true
  }
}

POST/api/v1/orders/{id}/ready

Mark ready (buzz). The order is ready. The customer's phone rings. "changed" is false when it was ready already, so a repeated call never buzzes twice.

Needs orders:write

Example
curl -X POST https://onebuzzfood.com/api/v1/orders/48213/ready \
  -H "Authorization: Bearer $ONEBUZZ_KEY"
{
  "success": true,
  "data": {
    "order": {
      "id": 48213,
      "code": "104",
      "status": "READY",
      "has_buzzer": true,
      "location_id": 3,
      "external_id": "kiosk-2026-000187",
      "customer_name": "Aman",
      "notes": "2× Margherita (Large), 1× Coke",
      "order_type": "TAKEAWAY",
      "table_no": null,
      "customer_phone": null,
      "buzz_count": 1,
      "customer": {
        "connected": true,
        "response": "ALERTING",
        "response_at": "2026-11-30T07:52:40Z"
      },
      "bill": {
        "id": 9917,
        "bill_no": 2451,
        "currency": "$",
        "subtotal": 52.5,
        "discount": 0,
        "tax_percent": 15,
        "tax_amount": 6.85,
        "round_off": 0,
        "total": 52.5,
        "payment_mode": "CARD",
        "paid": 52.5,
        "due": 0,
        "pay_state": "PAID",
        "items": [
          {
            "item_id": 12,
            "name": "Margherita",
            "variant": "Large",
            "type": "VEG",
            "qty": 2,
            "unit_price": 24,
            "line_total": 48,
            "note": null,
            "addons": []
          },
          {
            "item_id": 31,
            "name": "Coke",
            "variant": null,
            "type": "VEG",
            "qty": 1,
            "unit_price": 4.5,
            "line_total": 4.5,
            "note": null,
            "addons": []
          }
        ]
      },
      "created_at": "2026-11-30T07:41:12Z",
      "preparing_at": null,
      "ready_at": "2026-11-30T07:52:40Z",
      "delivered_at": null,
      "cancelled_at": null,
      "updated_at": "2026-11-30T07:41:12Z",
      "buzzer": {
        "join_url": "https://onebuzzfood.com/customer/join.php?t=…",
        "join_code": "482913"
      }
    },
    "changed": true,
    "alert": {
      "phones": 1,
      "sent": 1
    }
  }
}

POST/api/v1/orders/{id}/buzz

Buzz again. Rings the customer once more. Only for a READY order with a buzzer.

Needs orders:write

Example
curl -X POST https://onebuzzfood.com/api/v1/orders/48213/buzz \
  -H "Authorization: Bearer $ONEBUZZ_KEY"
{
  "success": true,
  "data": {
    "order": {
      "id": 48213,
      "code": "104",
      "status": "READY",
      "has_buzzer": true,
      "location_id": 3,
      "external_id": "kiosk-2026-000187",
      "customer_name": "Aman",
      "notes": "2× Margherita (Large), 1× Coke",
      "order_type": "TAKEAWAY",
      "table_no": null,
      "customer_phone": null,
      "buzz_count": 2,
      "customer": {
        "connected": false,
        "response": "NONE",
        "response_at": null
      },
      "bill": {
        "id": 9917,
        "bill_no": 2451,
        "currency": "$",
        "subtotal": 52.5,
        "discount": 0,
        "tax_percent": 15,
        "tax_amount": 6.85,
        "round_off": 0,
        "total": 52.5,
        "payment_mode": "CARD",
        "paid": 52.5,
        "due": 0,
        "pay_state": "PAID",
        "items": [
          {
            "item_id": 12,
            "name": "Margherita",
            "variant": "Large",
            "type": "VEG",
            "qty": 2,
            "unit_price": 24,
            "line_total": 48,
            "note": null,
            "addons": []
          },
          {
            "item_id": 31,
            "name": "Coke",
            "variant": null,
            "type": "VEG",
            "qty": 1,
            "unit_price": 4.5,
            "line_total": 4.5,
            "note": null,
            "addons": []
          }
        ]
      },
      "created_at": "2026-11-30T07:41:12Z",
      "preparing_at": null,
      "ready_at": null,
      "delivered_at": null,
      "cancelled_at": null,
      "updated_at": "2026-11-30T07:41:12Z",
      "buzzer": {
        "join_url": "https://onebuzzfood.com/customer/join.php?t=…",
        "join_code": "482913"
      }
    },
    "changed": true,
    "alert": {
      "phones": 1,
      "sent": 1
    }
  }
}

POST/api/v1/orders/{id}/delivered

Mark delivered. The customer has the order. It leaves the Live board and the buzzer link stops working.

Needs orders:write

Example
curl -X POST https://onebuzzfood.com/api/v1/orders/48213/delivered \
  -H "Authorization: Bearer $ONEBUZZ_KEY"
{
  "success": true,
  "data": {
    "order": {
      "id": 48213,
      "code": "104",
      "status": "DELIVERED",
      "has_buzzer": true,
      "location_id": 3,
      "external_id": "kiosk-2026-000187",
      "customer_name": "Aman",
      "notes": "2× Margherita (Large), 1× Coke",
      "order_type": "TAKEAWAY",
      "table_no": null,
      "customer_phone": null,
      "buzz_count": 0,
      "customer": {
        "connected": false,
        "response": "NONE",
        "response_at": null
      },
      "bill": {
        "id": 9917,
        "bill_no": 2451,
        "currency": "$",
        "subtotal": 52.5,
        "discount": 0,
        "tax_percent": 15,
        "tax_amount": 6.85,
        "round_off": 0,
        "total": 52.5,
        "payment_mode": "CARD",
        "paid": 52.5,
        "due": 0,
        "pay_state": "PAID",
        "items": [
          {
            "item_id": 12,
            "name": "Margherita",
            "variant": "Large",
            "type": "VEG",
            "qty": 2,
            "unit_price": 24,
            "line_total": 48,
            "note": null,
            "addons": []
          },
          {
            "item_id": 31,
            "name": "Coke",
            "variant": null,
            "type": "VEG",
            "qty": 1,
            "unit_price": 4.5,
            "line_total": 4.5,
            "note": null,
            "addons": []
          }
        ]
      },
      "created_at": "2026-11-30T07:41:12Z",
      "preparing_at": null,
      "ready_at": null,
      "delivered_at": "2026-11-30T07:55:02Z",
      "cancelled_at": null,
      "updated_at": "2026-11-30T07:41:12Z",
      "buzzer": null
    },
    "changed": true
  }
}

POST/api/v1/orders/{id}/cancel

Cancel. Cancels an order that is not delivered yet. Its bill no longer counts as a sale, and stock and loyalty points go back.

Needs orders:write

Example
curl -X POST https://onebuzzfood.com/api/v1/orders/48213/cancel \
  -H "Authorization: Bearer $ONEBUZZ_KEY"
{
  "success": true,
  "data": {
    "order": {
      "id": 48213,
      "code": "104",
      "status": "CANCELLED",
      "has_buzzer": true,
      "location_id": 3,
      "external_id": "kiosk-2026-000187",
      "customer_name": "Aman",
      "notes": "2× Margherita (Large), 1× Coke",
      "order_type": "TAKEAWAY",
      "table_no": null,
      "customer_phone": null,
      "buzz_count": 0,
      "customer": {
        "connected": false,
        "response": "NONE",
        "response_at": null
      },
      "bill": {
        "id": 9917,
        "bill_no": 2451,
        "currency": "$",
        "subtotal": 52.5,
        "discount": 0,
        "tax_percent": 15,
        "tax_amount": 6.85,
        "round_off": 0,
        "total": 52.5,
        "payment_mode": "CARD",
        "paid": 52.5,
        "due": 0,
        "pay_state": "PAID",
        "items": [
          {
            "item_id": 12,
            "name": "Margherita",
            "variant": "Large",
            "type": "VEG",
            "qty": 2,
            "unit_price": 24,
            "line_total": 48,
            "note": null,
            "addons": []
          },
          {
            "item_id": 31,
            "name": "Coke",
            "variant": null,
            "type": "VEG",
            "qty": 1,
            "unit_price": 4.5,
            "line_total": 4.5,
            "note": null,
            "addons": []
          }
        ]
      },
      "created_at": "2026-11-30T07:41:12Z",
      "preparing_at": null,
      "ready_at": null,
      "delivered_at": null,
      "cancelled_at": "2026-11-30T07:45:10Z",
      "updated_at": "2026-11-30T07:41:12Z",
      "buzzer": null
    },
    "changed": true
  }
}

Menu

Categories, items, sizes and add-ons, and marking an item sold out.

GET/api/v1/menu

The menu. Every category and item, with sizes ("variants"), add-on groups and whether the item is available now.

Needs menu:read

Example
curl https://onebuzzfood.com/api/v1/menu \
  -H "Authorization: Bearer $ONEBUZZ_KEY"
{
  "success": true,
  "data": {
    "currency": "$",
    "tax": {
      "label": "GST",
      "percent": 15,
      "included_in_prices": true
    },
    "categories": [
      {
        "id": 2,
        "name": "Pizza",
        "items": [
          {
            "id": 12,
            "name": "Margherita",
            "description": null,
            "type": "VEG",
            "price": 18,
            "variants": [
              {
                "name": "Regular",
                "price": 18
              },
              {
                "name": "Large",
                "price": 24
              }
            ],
            "available": true,
            "photo": null,
            "addon_group_ids": [
              1
            ]
          }
        ]
      }
    ],
    "addon_groups": [
      {
        "id": 1,
        "name": "Extra toppings",
        "min": 0,
        "max": 3,
        "options": [
          {
            "name": "Extra cheese",
            "price": 3
          }
        ]
      }
    ]
  }
}

PATCH/api/v1/menu/items/{id}

Item available or sold out. A sold-out item cannot be ordered on the POS or through the API until it is available again.

Needs menu:write

Body (JSON)

availableneededbooleantrue = available, false = sold out.
Example
curl -X PATCH https://onebuzzfood.com/api/v1/menu/items/48213 \
  -H "Authorization: Bearer $ONEBUZZ_KEY" \
  -H "Content-Type: application/json" \
  -d '{"available":false}'
{
  "success": true,
  "data": {
    "item": {
      "id": 12,
      "name": "Margherita",
      "available": false
    },
    "changed": true
  }
}

Tables

The tables of an outlet and what is running on them.

GET/api/v1/tables

Tables. Each table is FREE, HELD (an order is held on it, not billed yet) or RUNNING (a saved order is still open).

Needs tables:read

Query

location_idintegerThe outlet. Needed only when the restaurant has more than one and the key is not tied to one.
Example
curl https://onebuzzfood.com/api/v1/tables \
  -H "Authorization: Bearer $ONEBUZZ_KEY"
{
  "success": true,
  "data": {
    "location_id": 3,
    "enabled": true,
    "tables": [
      {
        "id": 1,
        "name": "1",
        "state": "FREE",
        "held": null,
        "running": null
      },
      {
        "id": 2,
        "name": "2",
        "state": "RUNNING",
        "held": null,
        "running": {
          "order_id": 48213,
          "code": "104",
          "status": "PREPARING",
          "total": 52.5,
          "due": 0
        }
      }
    ]
  }
}

Sales

Totals for a range of days. Cancelled orders are left out.

GET/api/v1/sales/summary

Sales summary. Bills, sales, tax, what is still unpaid, the split by payment and order type, each day and the 50 most sold items. Old months that were moved into a sales file are no longer counted.

Needs sales:read

Query

location_idintegerThe outlet. Needed only when the restaurant has more than one and the key is not tied to one.
fromdateFirst day, YYYY-MM-DD. Default today.
todateLast day. At most 92 days in one call.
Example
curl https://onebuzzfood.com/api/v1/sales/summary \
  -H "Authorization: Bearer $ONEBUZZ_KEY"
{
  "success": true,
  "data": {
    "from": "2026-11-01",
    "to": "2026-11-30",
    "timezone": "Pacific/Auckland",
    "location_id": null,
    "currency": "$",
    "bills": 1840,
    "sales": 48230.5,
    "tax": 6290.93,
    "discount": 210,
    "unpaid": 52.5,
    "average_bill": 26.21,
    "cancelled_orders": 12,
    "by_payment": {
      "CASH": 9120,
      "CARD": 39058,
      "UNPAID": 52.5
    },
    "by_order_type": {
      "TAKEAWAY": {
        "bills": 1210,
        "sales": 31120
      },
      "DINE_IN": {
        "bills": 630,
        "sales": 17110.5
      }
    },
    "by_day": [
      {
        "date": "2026-11-01",
        "bills": 58,
        "sales": 1520.5
      }
    ],
    "top_items": [
      {
        "name": "Margherita",
        "variant": "Large",
        "qty": 412,
        "sales": 9888
      }
    ]
  }
}

Staff

The team and their login hours. Read only. Pay and payslips are not in the API.

GET/api/v1/staff

The team. Owner, managers, staff and HR logins. Email addresses are not included.

Needs staff:read

Example
curl https://onebuzzfood.com/api/v1/staff \
  -H "Authorization: Bearer $ONEBUZZ_KEY"
{
  "success": true,
  "data": {
    "staff": [
      {
        "id": 21,
        "name": "Simran",
        "role": "manager",
        "active": true,
        "location_id": 3,
        "last_login_at": "2026-11-30T03:02:11Z",
        "created_at": "2026-08-02T10:00:00Z"
      }
    ]
  }
}

GET/api/v1/staff/hours

Login hours. How long each manager, staff member and HR login was signed in, with breaks taken out. In seconds. Owners are not timed.

Needs staff:read

Query

fromdateFirst day, YYYY-MM-DD. Default today.
todateLast day. At most 62 days in one call.
Example
curl https://onebuzzfood.com/api/v1/staff/hours \
  -H "Authorization: Bearer $ONEBUZZ_KEY"
{
  "success": true,
  "data": {
    "from": "2026-11-24",
    "to": "2026-11-30",
    "timezone": "Pacific/Auckland",
    "staff": [
      {
        "id": 21,
        "name": "Simran",
        "role": "manager",
        "signed_in_seconds": 151200,
        "break_seconds": 9000,
        "worked_seconds": 142200,
        "days_worked": 6,
        "signed_in_now": true,
        "on_break": null,
        "by_day": [
          {
            "date": "2026-11-24",
            "worked_seconds": 24300
          }
        ]
      }
    ],
    "total_worked_seconds": 142200
  }
}

Webhooks

OneBuzz calls your address when an order changes.

GET/api/v1/webhooks

List webhooks. The restaurant's webhooks and the events that exist.

Needs webhooks:write

Example
curl https://onebuzzfood.com/api/v1/webhooks \
  -H "Authorization: Bearer $ONEBUZZ_KEY"
{
  "success": true,
  "data": {
    "webhooks": [
      {
        "id": 2,
        "url": "https://example.com/onebuzz",
        "events": [
          "order.created",
          "order.ready"
        ],
        "location_id": null,
        "status": "ACTIVE",
        "last_status": 200,
        "last_delivery_at": "2026-11-30T07:52:41Z",
        "created_at": "2026-11-12T09:05:00Z"
      }
    ],
    "events": [
      "order.created",
      "order.updated",
      "order.preparing",
      "order.ready",
      "order.buzzed",
      "order.customer_coming",
      "order.delivered",
      "order.cancelled"
    ]
  }
}

POST/api/v1/webhooks

Add a webhook. The answer has the signing secret. It is shown only this once. A restaurant can have 5 webhooks.

Needs webhooks:write

Body (JSON)

urlneededstringYour https address.
eventsarrayThe events you want. Leave it out for all of them.
location_idintegerOnly this outlet's orders. Leave it out for every outlet.
Example
curl -X POST https://onebuzzfood.com/api/v1/webhooks \
  -H "Authorization: Bearer $ONEBUZZ_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/onebuzz","events":["order.created","order.ready"]}'
{
  "success": true,
  "data": {
    "webhook": {
      "id": 2,
      "url": "https://example.com/onebuzz",
      "events": [
        "order.created",
        "order.ready"
      ],
      "location_id": null,
      "status": "ACTIVE",
      "last_status": null,
      "last_delivery_at": null,
      "created_at": "2026-11-12T09:05:00Z"
    },
    "secret": "whsec_…"
  }
}

DELETE/api/v1/webhooks/{id}

Remove a webhook. Deliveries to it stop straight away.

Needs webhooks:write

Example
curl -X DELETE https://onebuzzfood.com/api/v1/webhooks/48213 \
  -H "Authorization: Bearer $ONEBUZZ_KEY"
{
  "success": true,
  "data": {
    "deleted": true,
    "id": 2
  }
}

Webhook events

OneBuzz sends a POST with JSON to your https address within a few seconds, whether the change was made through the API, on the POS or on the Live board. Answer with any 2xx status within 8 seconds. If you do not, the delivery is tried again after 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours. A webhook that fails 20 deliveries in a row is switched off, and the owner can switch it on again.

EventWhen
order.createdA new order or buzzer was made
order.updatedItems were added or changed, or the bill was paid
order.preparingThe kitchen started the order
order.readyThe order is ready (the customer is buzzed)
order.buzzedThe customer was buzzed again
order.customer_comingThe customer tapped "I'm coming"
order.deliveredThe order was handed over
order.cancelledThe order was cancelled

What arrives

Headers: X-OneBuzz-Event, X-OneBuzz-Delivery (the same number on every retry, so you can skip one you already handled) and X-OneBuzz-Signature.

{
  "id": "evt_5f2c9a1b7d3e4f6a8b0c1d2e",
  "event": "order.ready",
  "api_version": "v1",
  "created_at": "2026-11-30T07:52:40Z",
  "restaurant_id": 7,
  "location_id": 3,
  "data": {
    "order": {
      "id": 48213,
      "code": "104",
      "status": "READY",
      "has_buzzer": true,
      "location_id": 3,
      "external_id": "kiosk-2026-000187",
      "customer_name": "Aman",
      "notes": "2× Margherita (Large), 1× Coke",
      "order_type": "TAKEAWAY",
      "table_no": null,
      "customer_phone": null,
      "buzz_count": 1,
      "customer": {
        "connected": false,
        "response": "NONE",
        "response_at": null
      },
      "bill": {
        "id": 9917,
        "bill_no": 2451,
        "currency": "$",
        "subtotal": 52.5,
        "discount": 0,
        "tax_percent": 15,
        "tax_amount": 6.85,
        "round_off": 0,
        "total": 52.5,
        "payment_mode": "CARD",
        "paid": 52.5,
        "due": 0,
        "pay_state": "PAID",
        "items": [
          {
            "item_id": 12,
            "name": "Margherita",
            "variant": "Large",
            "type": "VEG",
            "qty": 2,
            "unit_price": 24,
            "line_total": 48,
            "note": null,
            "addons": []
          },
          {
            "item_id": 31,
            "name": "Coke",
            "variant": null,
            "type": "VEG",
            "qty": 1,
            "unit_price": 4.5,
            "line_total": 4.5,
            "note": null,
            "addons": []
          }
        ]
      },
      "created_at": "2026-11-30T07:41:12Z",
      "preparing_at": null,
      "ready_at": null,
      "delivered_at": null,
      "cancelled_at": null,
      "updated_at": "2026-11-30T07:41:12Z"
    }
  }
}

Check the signature

The header looks like t=1764489160,v1=…. v1 is the HMAC-SHA256 of t + "." + body with your webhook's secret. Refuse anything that does not match.

const crypto = require('crypto');

// rawBody: the request body exactly as it arrived (a string, before JSON.parse)
function isFromOneBuzz(rawBody, header, secret) {
  const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header || '');
  if (!m) return false;
  if (Math.abs(Date.now() / 1000 - Number(m[1])) > 300) return false; // older than 5 minutes
  const want = crypto.createHmac('sha256', secret).update(m[1] + '.' + rawBody).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(want), Buffer.from(m[2]));
}

Errors & limits

Each key may make 120 requests a minute. Every answer carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds). Over the limit you get 429 with a Retry-After header.

StatusCodeMeaning
401UNAUTHENTICATEDNo API key was sent.
401INVALID_API_KEYThe key is wrong or was removed.
402SUBSCRIPTION_EXPIREDThe restaurant's OneBuzz plan has ended.
403FORBIDDENThe key does not have the permission (scope) this endpoint needs, or it is tied to another outlet.
403API_NOT_ENABLEDThe API is not switched on for this restaurant.
404ORDER_NOT_FOUNDNo such order in this restaurant.
409INVALID_STATEThe order cannot take this step now, for example "ready" on a delivered order.
422VALIDATION_ERRORSomething in the request is missing or wrong. The message says what.
422ITEM_UNAVAILABLEAn item in the order is marked sold out.
429RATE_LIMITEDToo many requests. Wait for the seconds in the Retry-After header.
500SERVER_ERRORSomething went wrong on our side. Safe to try again.

Questions, or need something the API does not do yet? Contact Onebuzz Food.