The Lunchbox 2.0 POS API defines the contract between Lunchbox and a POS provider integration. Lunchbox retrieves store details and submits orders to the POS provider, and the POS provider notifies Lunchbox of store and order changes via webhooks.
openapi: 3.0.3
info:
title: Lunchbox POS API
description: >-
The Lunchbox 2.0 POS API defines the contract between Lunchbox and a POS
provider integration. Lunchbox retrieves store details and submits orders to
the POS provider, and the POS provider notifies Lunchbox of store and order
changes via webhooks. This specification documents the endpoints Lunchbox
calls on the POS provider, plus the inbound webhooks the POS provider sends
to Lunchbox (modeled as callbacks). All payloads are JSON.
version: '2.0'
contact:
name: Lunchbox Support
email: [email protected]
url: https://docs.lunchbox.io/
servers:
- url: https://{chain_name}.lunchbox.io/api/v2
description: Per-chain Lunchbox 2.0 POS API base URL
variables:
chain_name:
default: chain
description: The restaurant chain's Lunchbox subdomain
security:
- tokenAuth: []
tags:
- name: Stores
description: Retrieve POS store mappings and store details.
- name: Orders
description: Submit, retrieve, and update orders against the POS.
paths:
/pos/stores:
get:
tags: [Stores]
summary: Lunchbox Get Stores
operationId: posGetStores
responses:
'200':
description: List of POS store identifiers.
content:
application/json:
schema:
type: array
items:
type: object
properties:
pos_store_id:
type: string
examples:
PosGetStores200Example:
summary: Default posGetStores 200 response
x-microcks-default: true
value: {}
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/pos/stores/{store_id}:
parameters:
- name: store_id
in: path
required: true
schema:
type: string
get:
tags: [Stores]
summary: Lunchbox Get Store Details
operationId: posGetStoreDetails
responses:
'200':
description: Detailed POS store record.
content:
application/json:
schema:
$ref: '#/components/schemas/PosStore'
examples:
PosGetStoreDetails200Example:
summary: Default posGetStoreDetails 200 response
x-microcks-default: true
value: {}
callbacks:
storeUpdated:
'{$request.body#/lunchbox_webhook_url}':
post:
summary: Store Updated Webhook
description: >-
The POS provider triggers this webhook to notify Lunchbox that a
store has been added or updated. Lunchbox then calls Get Store
Details using the provided pos_store_id.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/StoreUpdateEvent'
responses:
'200':
description: Webhook acknowledged.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/pos/orders/{pos_store_id}:
parameters:
- $ref: '#/components/parameters/PosStoreId'
post:
tags: [Orders]
summary: Lunchbox Submit an Order
description: Lunchbox uses this call to submit orders to the POS.
operationId: posSubmitOrder
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PosOrder'
examples:
PosSubmitOrderRequestExample:
summary: Default posSubmitOrder request
x-microcks-default: true
value: {}
responses:
'200':
description: Order accepted by the POS.
content:
application/json:
schema:
$ref: '#/components/schemas/PosOrderAck'
examples:
PosSubmitOrder200Example:
summary: Default posSubmitOrder 200 response
x-microcks-default: true
value: {}
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/pos/orders/{pos_store_id}/{pos_order_id}:
parameters:
- $ref: '#/components/parameters/PosStoreId'
- name: pos_order_id
in: path
required: true
schema:
type: string
get:
tags: [Orders]
summary: Lunchbox Get an Order
operationId: posGetOrder
responses:
'200':
description: The requested POS order.
content:
application/json:
schema:
$ref: '#/components/schemas/PosOrder'
examples:
PosGetOrder200Example:
summary: Default posGetOrder 200 response
x-microcks-default: true
value: {}
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
put:
tags: [Orders]
summary: Lunchbox Update an Order
operationId: posUpdateOrder
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PosOrder'
examples:
PosUpdateOrderRequestExample:
summary: Default posUpdateOrder request
x-microcks-default: true
value: {}
responses:
'200':
description: Order updated.
callbacks:
orderUpdated:
'{$request.body#/lunchbox_webhook_url}':
post:
summary: Order Updated Webhook
description: >-
The POS provider triggers this webhook to notify Lunchbox that
an order has been updated from the POS provider's side.
Acceptable statuses are is_completed and is_canceled.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/OrderUpdateEvent'
responses:
'200':
description: Webhook acknowledged.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
securitySchemes:
tokenAuth:
type: apiKey
in: header
name: Authorization
description: 'Team token passed as: Authorization: Token <team_token>'
parameters:
PosStoreId:
name: pos_store_id
in: path
required: true
schema:
type: string
schemas:
PosStore:
type: object
properties:
pos_store_id:
type: string
example: '123456'
store_id:
type: string
example: '123456'
name:
type: string
example: Sample
contact:
$ref: '#/components/schemas/PosContact'
location:
$ref: '#/components/schemas/PosLocation'
PosContact:
type: object
properties:
active:
type: boolean
example: true
address1:
type: string
example: 1216 Broadway
address2:
type: string
nullable: true
example: string
address3:
type: string
nullable: true
example: string
city:
type: string
example: New York
state:
type: string
example: NY
postal_code:
type: string
example: '10001'
country:
type: string
example: US
phone:
type: string
example: '2125551411'
latitude:
type: number
example: 40.74661
longitude:
type: number
example: -73.98833
PosLocation:
type: object
properties:
hours:
type: array
items:
$ref: '#/components/schemas/PosHours'
example: []
PosHours:
type: object
properties:
iso_day_of_week:
type: integer
example: 1
start_time:
type: string
example: string
end_time:
type: string
example: string
PosOrder:
type: object
properties:
pos_store_id:
type: string
example: '123456'
order_id:
type: string
example: 1234
ready_ts:
type: string
format: date-time
example: '2023-07-25T06:00:00-04:00'
service_type_id:
type: integer
example: 1234
service_type:
type: string
example: string
status:
type: object
properties:
is_finalized:
type: boolean
is_completed:
type: boolean
is_canceled:
type: boolean
example: {}
customer:
type: object
properties:
first_name:
type: string
last_name:
type: string
phone:
type: string
company_name:
type: string
customer_id:
type: integer
email:
type: string
format: email
example: {}
location:
$ref: '#/components/schemas/PosOrderLocation'
charges:
type: object
properties:
total_cents:
type: integer
subtotal_cents:
type: integer
tax_cents:
type: integer
delivery_cents:
type: integer
tip_cents:
type: integer
remaining_cents:
type: integer
example: {}
PosOrderLocation:
type: object
properties:
address1:
type: string
example: 1216 Broadway
address2:
type: string
nullable: true
example: string
address3:
type: string
nullable: true
example: string
city:
type: string
example: New York
statecode:
type: string
example: NY
zipcode:
type: string
example: '10001'
province:
type: string
nullable: true
example: string
country:
type: string
example: US
phone:
type: string
nullable: true
example: '2125551411'
instructions:
type: string
example: string
PosOrderAck:
type: object
properties:
pos_store_id:
type: string
example: '123456'
pos_order_id:
type: string
example: 1234
status:
type: object
properties:
is_completed:
type: boolean
example: {}
StoreUpdateEvent:
type: object
required: [event_type, pos_store_id]
properties:
event_type:
type: string
enum: [store_update]
example: store_update
pos_store_id:
type: string
example: '123456'
OrderUpdateEvent:
type: object
required: [event_type, pos_store_id, pos_order_id]
properties:
event_type:
type: string
enum: [order_update]
example: order_update
pos_store_id:
type: string
example: '123456'
pos_order_id:
type: string
example: 1234