Using the Reservations API
This guide covers how to use ReceiptRoller's Reservations API (
/api/v1/reservations). Because you can operate the same reservation engine as the web dashboard's reservation management over OAuth, you can retrieve, create, and update the status of reservations, and generate reservation slots, from a mobile app or an external reservation system.Using the Reservations API
Required scopes
| Scope | Permissions granted |
|---|---|
store.reservations.read | Read reservations, reservation slots, table info, and statistics |
store.reservations.write | Create, modify, and update the status of reservations; create, generate, and delete reservation slots |
Check the box in "API scopes" on the app editing screen, and include the scope in the scope parameter of the authorization URL.
Authentication
This follows the same token conventions as the other v1 APIs.
- A token bound to a business account — call it as-is
- A user-scoped token (for native mobile apps) — append
?organizationId=to the query
Endpoints
| Method | Path | Description |
|---|---|---|
| GET | /api/v1/reservations?storeId= | List reservations (filter by status, from, to) |
| GET | /api/v1/reservations/{reservationId} | Reservation detail |
| POST | /api/v1/reservations | Create a reservation |
| PUT | /api/v1/reservations/{reservationId} | Update reservation details / change status |
| GET | /api/v1/reservations/slots | List reservation slots (by default, today plus 7 days) |
| POST | /api/v1/reservations/slots | Create a single reservation slot |
| POST | /api/v1/reservations/slots/generate | Bulk-generate reservation slots from the reservation settings |
| DELETE | /api/v1/reservations/slots/{slotId} | Delete a reservation slot |
| GET | /api/v1/reservations/config | The store's reservation settings (slot length, acceptance window, auto-confirmation, custom fields, etc.) |
| GET | /api/v1/reservations/tables | List the reservable seats (tables, private rooms, counters, etc.) |
| GET | /api/v1/reservations/stats?month= | Monthly reservation statistics (counts by status; today's / tomorrow's counts) |
In every case, specify storeId in the query or the body.
Creating a reservation
POST /api/v1/reservations
Authorization: Bearer {token}
Content-Type: application/json
{
"storeId": "store-001",
"customerName": "Taro Yamada",
"customerPhone": "090-0000-0000",
"partySize": 4,
"slotId": "slot-xxxx",
"note": "Would like a window seat"
}A reservation created via the API is recorded with bookingSource set to API (if you specify the value explicitly in the request, that value takes precedence).
Updating status
Changing status in the body of PUT /api/v1/reservations/{reservationId} runs the same status-transition processing as the web dashboard. The remaining-seat calculation for reservation slots, along with confirmation and cancellation notifications, behaves the same as operating from the dashboard.
Statuses you can specify:
Pending(awaiting approval)Confirmed(confirmed)Completed(visited)Cancelled(cancelled)NoShow(no-show)
Bulk-generating reservation slots
POST /api/v1/reservations/slots/generate generates reservation slots for a specified period in one operation, based on the store's reservation settings (slot length, business hours, regular closing days).
POST /api/v1/reservations/slots/generate
Authorization: Bearer {token}
Content-Type: application/json
{
"storeId": "store-001",
"from": "2026-06-15",
"to": "2026-06-21",
"perResource": true
}Setting perResource to true generates reservation slots for each reservable seat (table, private room, counter) registered in the store layout. Use this when you accept reservations per seat.
Retrieving table (seat) information
GET /api/v1/reservations/tables?storeId= returns the reservable resources registered in the store layout.
{
"items": [
{ "id": "table-01", "name": "Table 1", "type": "table", "typeDisplayName": "Table", "capacity": 4 },
{ "id": "room-01", "name": "Room A", "type": "room", "typeDisplayName": "Private room", "capacity": 8 }
]
}The id returned here can be specified as-is in the assignedResource of a reservation slot or a reservation. Edit the seat layout itself in the layout editor of the web dashboard.
Related guides
-
Using the Store Information APIA guide to the REST API for fetching and updating a store's basic information (store name, store type, contact details, and address). Lets you implement a store information editing screen from token-authenticated clients such as staff apps.
-
PosTransactionDto specification — field reference for transaction dataA complete field reference for PosTransactionDto, the canonical model for the transaction data ReceiptRoller handles. For each category — identifiers, dates, amounts, line items, payments, staff, status, and CRM linkage — it summarizes the field names, types, meanings, and how each POS vendor populates them. A reference for developers and external-system integrators. Also referenced from the Smaregi and Square mapping articles.
-
Purchase and receipt data integrationExplains the structure of the purchase and receipt data ReceiptRoller handles, how to retrieve it, related scopes, Webhooks, and common use cases.
-
Using the Business Hours APIA guide to ReceiptRoller's Business Hours API (/api/v1/stores/{storeId}/business-hours). Covers retrieving and updating per-day business hours, registering special business days (temporary closures and hour changes), configuring a store's workable hours (the upper bound for shift creation), and determining whether the store is currently open.
-
Using the Orders / OMS APIA guide to CRUD operations on the orders under a business account using ReceiptRoller's Orders / OMS API (/api/v1/orders). Covers creating, updating, transitioning status (confirm, process, cancel), and deleting orders, plus the flow for Android / iOS apps and server integrations.