A REST contract that a merchant's EPOS (point-of-sale) system implements so Dojo can read orders, tables, areas, parties, and reservations for hospitality integrations. The server is merchant-hosted (example server your-epos.example.com); the spec defines the interface Dojo consumes. Version 1.0 (15 paths).
{
"openapi": "3.1.0",
"info": {
"title": "EPOS Data API (REST)",
"version": "1.0",
"description": "REST contract that an external POS/EPOS system implements so Dojo products can\nfetch and update commerce entities (Orders, Tables, Areas, Parties, Reservations)\nand record payments. Use this when the EPOS exposes its own publicly reachable\nHTTP endpoints; for on-premise EPOSes that cannot accept inbound HTTP, use the\n[WebSocket variant](/epos-data-asyncapi/bundled.yaml) of the same contract.\n\nCore modules:\n- Tables\n- Areas\n- Orders\n- Parties\n- Reservations\n\nAPI modules can generally be\nimplemented independently, with a small number of interdependent fields affected\nby other modules (for example, if Parties are implemented & the information is\nknown, a `partyId` should be attached to an Order's `dineInDetails`).\n\nAll requests also contain special headers within the REST headers,\ncontaining details about the requestor that can be used for logging purposes or EPOS business logic\n(such as waiter id based access to entities).\n\nBefore any of these endpoints will be invoked by Dojo, register the capabilities you implement with `PUT /epos/integrations/rest`. See the EPOS Data API guide for the full registration flow."
},
"servers": [
{
"url": "https://your-epos.example.com",
"description": "The EPOS Data REST API has no shared base URL: each EPOS provider hosts the\nendpoints on their own domain and registers them against that base via\n`PUT /epos/integrations/rest`. The placeholder `https://your-epos.example.com`\nis illustrative — replace with your own publicly reachable HTTPS URL."
}
],
"tags": [
{
"name": "Areas"
},
{
"name": "Orders"
},
{
"name": "Parties"
},
{
"name": "Reservations"
},
{
"name": "Tables"
},
{
"name": "Events"
}
],
"paths": {
"/v1/areas": {
"get": {
"tags": [
"Areas"
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Area"
}
}
}
},
"description": "Successfully returns all areas"
},
"4XX": {
"description": "Client Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EPOSError"
}
}
}
},
"5XX": {
"description": "Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EPOSError"
}
}
}
}
},
"operationId": "v1-list-areas",
"summary": "List areas",
"description": "Retrieves all areas that are being served. Capability: `ListAreas`\n",
"parameters": [
{
"$ref": "#/components/parameters/WaiterId"
},
{
"$ref": "#/components/parameters/DojoRequestingProduct"
},
{
"$ref": "#/components/parameters/DeviceId"
},
{
"$ref": "#/components/parameters/DeviceType"
}
]
}
},
"/v1/orders": {
"post": {
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateOrderRequest"
}
}
},
"required": true
},
"tags": [
"Orders"
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Order"
}
}
},
"description": "."
},
"4XX": {
"description": "Client Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EPOSError"
}
}
}
},
"5XX": {
"description": "Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EPOSError"
}
}
}
}
},
"operationId": "v1-post-orders",
"summary": "Create an order",
"description": "Create an order on the EPOS. Capability: `CreateOrder`\n",
"parameters": [
{
"$ref": "#/components/parameters/WaiterId"
},
{
"$ref": "#/components/parameters/DojoRequestingProduct"
},
{
"$ref": "#/components/parameters/DeviceId"
},
{
"$ref": "#/components/parameters/DeviceType"
}
]
}
},
"/v1/orders/{orderId}": {
"get": {
"tags": [
"Orders"
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Order"
}
}
},
"description": "OK"
},
"4XX": {
"description": "Client Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EPOSError"
}
}
}
},
"5XX": {
"description": "Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EPOSError"
}
}
}
}
},
"operationId": "v1-get-orders-orderId",
"summary": "Get an order by id",
"description": "Retrieve details of an order using the order ID. Capability: `GetOrderById`\n"
},
"delete": {
"tags": [
"Orders"
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Order"
}
}
},
"description": "OK"
},
"4XX": {
"description": "Client Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EPOSError"
}
}
}
},
"5XX": {
"description": "Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EPOSError"
}
}
}
}
},
"operationId": "v1-delete-orders-orderId",
"summary": "Cancel an order by id",
"description": "Cancels an order by ID. Capability: `CancelOrderById`\n"
},
"parameters": [
{
"name": "orderId",
"description": "The ID of the order to retrieve.",
"schema": {
"type": "string"
},
"in": "path",
"required": true
},
{
"$ref": "#/components/parameters/WaiterId"
},
{
"$ref": "#/components/parameters/DojoRequestingProduct"
},
{
"$ref": "#/components/parameters/DeviceId"
},
{
"$ref": "#/components/parameters/DeviceType"
}
]
},
"/v1/orders/search": {
"post": {
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchOrdersRequest"
}
}
},
"required": true
},
"tags": [
"Orders"
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PagedOrdersResponse"
}
}
},
"description": "."
},
"4XX": {
"description": "Client Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EPOSError"
}
}
}
},
"5XX": {
"description": "Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EPOSError"
}
}
}
}
},
"summary": "Search orders",
"description": "Searches through the orders on the EPOS. Capability: `SearchOrders`\n",
"parameters": [
{
"$ref": "#/components/parameters/WaiterId"
},
{
"$ref": "#/components/parameters/DojoRequestingProduct"
},
{
"$ref": "#/components/parameters/DeviceId"
},
{
"$ref": "#/components/parameters/DeviceType"
}
]
}
},
"/v1/orders/{orderId}/lock": {
"post": {
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateOrderLockRequest"
}
}
},
"required": true
},
"tags": [
"Orders"
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Order"
}
}
},
"description": "Successful response with the order in its current state."
},
"409": {
"description": "Conflict, order currently cannot be locked",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EPOSError",
"example": {
"errorType": "Conflict",
"debugMessage": "The order is already locked by waiter Joe at till 123",
"traceId": "some-internal-trace-guid"
}
}
}
}
},
"4XX": {
"description": "Client Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EPOSError"
}
}
}
},
"5XX": {
"description": "Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EPOSError"
}
}
}
}
},
"operationId": "v1-post-order-lock",
"summary": "Lock an EPOS Order",
"description": "Request a Dojo write lock on an EPOS Order, returning the latest version of the Order once locked. Capability: CreateOrderLock\n",
"parameters": [
{
"$ref": "#/components/parameters/WaiterId"
},
{
"$ref": "#/components/parameters/DojoRequestingProduct"
},
{
"$ref": "#/components/parameters/DeviceId"
},
{
"$ref": "#/components/parameters/DeviceType"
}
]
},
"parameters": [
{
"name": "orderId",
"description": "The ID of the order to lock.",
"schema": {
"type": "string"
},
"in": "path",
"required": true
}
]
},
"/v1/orders/{orderId}/locks/{lockId}": {
"delete": {
"tags": [
"Orders"
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Order"
}
}
},
"description": "The order in the state after the lock has been released"
},
"4XX": {
"description": "Client Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EPOSError"
}
}
}
},
"5XX": {
"description": "Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EPOSError"
}
}
}
}
},
"operationId": "v1-delete-order-lock",
"summary": "Unlock an EPOS Order",
"description": "Request to release a Dojo write lock on an EPOS Order, returning the latest version of the Order once unlocked. Capability: `DeleteOrderLock`\n",
"parameters": [
{
"$ref": "#/components/parameters/WaiterId"
},
{
"$ref": "#/components/parameters/DojoRequestingProduct"
},
{
"$ref": "#/components/parameters/DeviceId"
},
{
"$ref": "#/components/parameters/DeviceType"
}
]
},
"put": {
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExtendOrderLockRequest"
}
}
},
"required": true
},
"tags": [
"Orders"
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExtendOrderLockResponse"
}
}
},
"description": "."
},
"4XX": {
"description": "Client Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EPOSError"
}
}
}
},
"5XX": {
"description": "Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EPOSError"
}
}
}
}
},
"operationId": "v1-put-extend-order-lock",
"summary": "Extend an EPOS Order Lock",
"description": "Request a Dojo write lock on an EPOS Order is extended, returning the latest version of the Order. Capability: `ExtendOrderLock`\n",
"parameters": [
{
"$ref": "#/components/parameters/WaiterId"
},
{
"$ref": "#/components/parameters/DojoRequestingProduct"
},
{
"$ref": "#/components/parameters/DeviceId"
},
{
"$ref": "#/components/parameters/DeviceType"
}
]
},
"parameters": [
{
"name": "orderId",
"description": "The ID of the order to unlock.",
"schema": {
"type": "string"
},
"in": "path",
"required": true
},
{
"name": "lockId",
"description": "The unique ID of a lock generated by Dojo. Consuming this isn't strictly required as Dojo will create at most one lock per order, but it can be useful for tracking the lifecycle of any lock.",
"schema": {
"type": "string"
},
"in": "path",
"required": true
}
]
},
"/v1/orders/{orderId}/bill": {
"get": {
"tags": [
"Orders"
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OrderBill"
}
}
},
"description": "Successful response with the bill for an order."
},
"4XX": {
"description": "Client Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EPOSError"
}
}
}
},
"5XX": {
"description": "Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EPOSError"
}
}
}
}
},
"operationId": "v1-get-orders-bill",
"summary": "Get a printable bill",
"description": "Retrieve a printable version of the Order, specifying the Header and Footer sections as it should be printed on the terminal. Capability: `GetOrderBill`",
"parameters": [
{
"$ref": "#/components/parameters/WaiterId"
},
{
"$ref": "#/components/parameters/DojoRequestingProduct"
},
{
"$ref": "#/components/parameters/DeviceId"
},
{
"$ref": "#/components/parameters/DeviceType"
}
]
},
"parameters": [
{
"name": "orderId",
"description": "The ID of the order to get the bill for.",
"schema": {
"type": "string"
},
"in": "path",
"required": true
}
]
},
"/v1/orders/{orderId}/record-payment": {
"post": {
"tags": [
"Orders"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PaymentWithLockId"
}
}
},
"required": true
},
"responses": {
"200": {
"description": ".",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Order"
}
}
}
},
"4XX": {
"description": "Client Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EPOSError"
}
}
}
},
"5XX": {
"description": "Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EPOSError"
}
}
}
}
},
"summary": "Record Payment Request",
"operationId": "v1-post-record-order-payment",
"description": "Request to record a payment against this order. If the payment cannot be recorded, use the error messages and Dojo will reverse/release/refund the payment. Capability: `RecordOrderPayment`",
"parameters": [
{
"$ref": "#/components/parameters/WaiterId"
},
{
"$ref": "#/components/parameters/DojoRequestingProduct"
},
{
"$ref": "#/components/parameters/DeviceId"
},
{
"$ref": "#/components/parameters/DeviceType"
}
]
},
"parameters": [
{
"name": "orderId",
"description": "The ID of the order to record the payment against",
"schema": {
"type": "string"
},
"in": "path",
"required": true
}
]
},
"/v1/parties": {
"post": {
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreatePartyRequest"
}
}
}
},
"tags": [
"Parties"
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Party"
}
}
},
"description": "Party successfully created."
},
"4XX": {
"description": "Client Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EPOSError"
}
}
}
},
"5XX": {
"description": "Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EPOSError"
}
}
}
}
},
"operationId": "v1-post-parties",
"summary": "Create party",
"description": "Create a new party in the POS domain. Capability: `CreateParty`\n",
"parameters": [
{
"$ref": "#/components/parameters/WaiterId"
},
{
"$ref": "#/components/parameters/DojoRequestingProduct"
},
{
"$ref": "#/components/parameters/DeviceId"
},
{
"$ref": "#/components/parameters/DeviceType"
}
]
}
},
"/v1/parties/{partyId}": {
"get": {
"tags": [
"Parties"
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Party"
}
}
},
"description": "Ok"
},
"4XX": {
"description": "Client Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EPOSError"
}
}
}
},
"5XX": {
"description": "Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EPOSError"
}
}
}
}
},
"operationId": "v1-get-parties-partyId",
"summary": "Get party",
"description": "Retrieves a specific party. Capability: `GetPartyById`\n"
},
"put": {
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdatePartyRequest"
}
}
}
},
"tags": [
"Parties"
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Party"
}
}
},
"description": "Party successfully updated."
},
"4XX": {
"description": "Client Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EPOSError"
}
}
}
},
"5XX": {
"description": "Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EPOSError"
}
}
}
}
},
"operationId": "v1-put-parties-partyId",
"summary": "Update party",
"description": "Sets the party's details to those provided. Capability: `UpdatePartyById`\n"
},
"delete": {
"tags": [
"Parties"
],
"responses": {
"200": {
"description": "."
},
"4XX": {
"description": "Client Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EPOSError"
}
}
}
},
"5XX": {
"description": "Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EPOSError"
}
}
}
}
},
"operationId": "v1-delete-parties-partyId",
"summary": "Delete party",
"description": "Deletes a specific party. Capability: `DeletePartyById`\n"
},
"parameters": [
{
"name": "partyId",
"description": "The ID of the party to retrieve.",
"schema": {
"type": "string"
},
"in": "path",
"required": true
},
{
"$ref": "#/components/parameters/WaiterId"
},
{
"$ref": "#/components/parameters/DojoRequestingProduct"
},
{
"$ref": "#/components/parameters/DeviceId"
},
{
"$ref": "#/components/parameters/DeviceType"
}
]
},
"/v1/reservations": {
"post": {
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateReservationRequest"
}
}
}
},
"tags": [
"Reservations"
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Reservation"
}
}
},
"description": "Reservation successfully created."
},
"4XX": {
"description": "Client Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EPOSError"
}
}
}
},
"5XX": {
"description": "Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EPOSError"
}
}
}
}
},
"operationId": "v1-post-reservations",
"summary": "Create reservation",
"description": "Create a new reservation in the POS domain. Capability: `CreateReservation`\n",
"parameters": [
{
"$ref": "#/components/parameters/WaiterId"
},
{
"$ref": "#/components/parameters/DojoRequestingProduct"
},
{
"$ref": "#/components/parameters/DeviceId"
},
{
"$ref": "#/components/parameters/DeviceType"
}
]
}
},
"/v1/reservations/{reservationId}": {
"get": {
"tags": [
"Reservations"
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Reservation"
}
}
},
"description": "Ok"
},
"4XX": {
"description": "Client Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EPOSError"
}
}
}
},
"5XX": {
"description": "Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EPOSError"
}
}
}
}
},
"operationId": "v1-get-reservations-reservationId",
"summary": "Get reservation",
"description": "Retrieves a specific reservation. Capability: `GetReservationById`\n"
},
"put": {
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateReservationRequest"
}
}
}
},
"tags": [
"Reservations"
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Reservation"
}
}
},
"description": "Reservation successfully updated."
},
"4XX": {
"description": "Client Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EPOSError"
}
}
}
},
"5XX": {
"description": "Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EPOSError"
}
}
}
}
},
"operationId": "v1-put-reservations-reservationId",
"summary": "Update reservation",
"description": "Sets the reservation's details to those provided. Capbility: `UpdateReservationById`\n"
},
"delete": {
"tags": [
"Reservations"
],
"responses": {
"200": {
"description": "."
},
"4XX": {
"description": "Client Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EPOSError"
}
}
}
},
"5XX": {
"description": "Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EPOSError"
}
}
}
}
},
"operationId": "v1-delete-reservations-reservationId",
"summary": "Delete reservation",
"description": "Deletes a specific reservation. Capability: `DeleteReservationById`\n"
},
"parameters": [
{
"name": "reservationId",
"description": "The ID of the reservation to retrieve.",
"schema": {
"type": "string"
},
"in": "path",
"required": true
},
{
"$ref": "#/components/parameters/WaiterId"
},
{
"$ref": "#/components/parameters/DojoRequestingProduct"
},
{
"$ref": "#/components/parameters/DeviceId"
},
{
"$ref": "#/components/parameters/DeviceType"
}
]
},
"/v1/reservations/search": {
"post": {
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchReservationsRequest"
}
}
},
"required": true
},
"tags": [
"Reservations"
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PagedReservationsResponse"
}
}
},
"description": "Ok"
},
"4XX": {
"description": "Client Error",
"content": {
"application/json": {
"schema": {
# --- truncated at 32 KB (113 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/dojo/refs/heads/main/openapi/dojo-epos-data-api.json