Flipdish Devices API
Manage card readers, kiosk and terminal IoT devices, and device heartbeats.
OpenAPI Specification
{
"openapi": "3.0.3",
"info": {
"title": "Flipdish API - Devices",
"version": "v1.0",
"description": "Flipdish Open API v1.0 \u2014 Devices operations. Flipdish is an online ordering and branded-app platform for restaurants and takeaways. This specification was derived from the official Flipdish Swagger document and grouped by resource domain.",
"contact": {
"name": "Flipdish Support",
"email": "[email protected]",
"url": "https://help.flipdish.com"
},
"x-generated-from": "https://api.flipdish.co/swagger/docs/v1.0",
"x-last-validated": "2026-06-02"
},
"servers": [
{
"url": "https://api.flipdish.co",
"description": "Flipdish production API"
}
],
"security": [
{
"oauth2": [
"api"
]
}
],
"tags": [
{
"name": "CardReaders",
"description": "Operations for Card Readers."
},
{
"name": "Device",
"description": "Operations for Device."
},
{
"name": "Heartbeat",
"description": "Operations for Heartbeat."
},
{
"name": "KioskEntitlements",
"description": "Operations for Kiosk Entitlements."
},
{
"name": "KioskIot",
"description": "Operations for Kiosk Iot."
},
{
"name": "TerminalIot",
"description": "Operations for Terminal Iot."
}
],
"paths": {
"/api/v1.0/{appId}/stripeterminal/connectiontoken": {
"get": {
"tags": [
"CardReaders"
],
"operationId": "GetStripeConnectionToken",
"parameters": [
{
"name": "appId",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "The app id path parameter.",
"example": "500123"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RestApiResult_StripeTerminalConnectionToken_"
},
"examples": {
"GetStripeConnectionToken200Example": {
"summary": "Default GetStripeConnectionToken 200 response",
"x-microcks-default": true,
"value": {
"Data": {
"Token": "string"
}
}
}
}
}
}
},
"400": {
"description": "BadRequest",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FlipdishError"
},
"examples": {
"GetStripeConnectionToken400Example": {
"summary": "Default GetStripeConnectionToken 400 response",
"x-microcks-default": true,
"value": {
"error": {
"errorMessage": "Invalid or missing parameters.",
"errorCode": "BadRequest",
"details": "Validation failed for field 'storeId'."
}
}
}
}
}
}
},
"401": {
"description": "Authentication has been denied for this request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FlipdishError"
},
"examples": {
"GetStripeConnectionToken401Example": {
"summary": "Default GetStripeConnectionToken 401 response",
"x-microcks-default": true,
"value": {
"error": {
"errorMessage": "Invalid or missing parameters.",
"errorCode": "BadRequest",
"details": "Validation failed for field 'storeId'."
}
}
}
}
}
}
},
"403": {
"description": "Successful authentication, but authorization has been denied for this request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FlipdishError"
},
"examples": {
"GetStripeConnectionToken403Example": {
"summary": "Default GetStripeConnectionToken 403 response",
"x-microcks-default": true,
"value": {
"error": {
"errorMessage": "Invalid or missing parameters.",
"errorCode": "BadRequest",
"details": "Validation failed for field 'storeId'."
}
}
}
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FlipdishError"
},
"examples": {
"GetStripeConnectionToken500Example": {
"summary": "Default GetStripeConnectionToken 500 response",
"x-microcks-default": true,
"value": {
"error": {
"errorMessage": "Invalid or missing parameters.",
"errorCode": "BadRequest",
"details": "Validation failed for field 'storeId'."
}
}
}
}
}
}
}
},
"security": [
{
"oauth2": [
"api"
]
}
],
"summary": "Flipdish Get Stripe Connection Token",
"description": "Get Stripe Connection Token via the Flipdish Open API v1.0 (GET /api/v1.0/{appId}/stripeterminal/connectiontoken).",
"x-microcks-operation": {
"delay": 0,
"dispatcher": "FALLBACK"
}
}
},
"/api/v1.0/{appId}/payments/terminals/stripe/{readerId}": {
"get": {
"tags": [
"CardReaders"
],
"operationId": "CardReaders_GetReader",
"parameters": [
{
"name": "readerId",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "The reader id path parameter.",
"example": "500123"
},
{
"name": "appId",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "The app id path parameter.",
"example": "500123"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RestApiResult_CardReader_"
},
"examples": {
"CardReaders_GetReader200Example": {
"summary": "Default CardReaders_GetReader 200 response",
"x-microcks-default": true,
"value": {
"Data": {
"Id": "500123",
"DeviceSoftwareVersion": "string",
"SerialNumber": "string",
"Status": "Active",
"RegistrationCode": "string",
"DeviceType": "string",
"Deleted": true,
"Action": {
"ActionState": "string",
"FailureCode": "string",
"FailureMessage": "string",
"Type": "string"
}
}
}
}
}
}
}
},
"400": {
"description": "BadRequest",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FlipdishError"
},
"examples": {
"CardReaders_GetReader400Example": {
"summary": "Default CardReaders_GetReader 400 response",
"x-microcks-default": true,
"value": {
"error": {
"errorMessage": "Invalid or missing parameters.",
"errorCode": "BadRequest",
"details": "Validation failed for field 'storeId'."
}
}
}
}
}
}
},
"401": {
"description": "Authentication has been denied for this request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FlipdishError"
},
"examples": {
"CardReaders_GetReader401Example": {
"summary": "Default CardReaders_GetReader 401 response",
"x-microcks-default": true,
"value": {
"error": {
"errorMessage": "Invalid or missing parameters.",
"errorCode": "BadRequest",
"details": "Validation failed for field 'storeId'."
}
}
}
}
}
}
},
"403": {
"description": "Successful authentication, but authorization has been denied for this request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FlipdishError"
},
"examples": {
"CardReaders_GetReader403Example": {
"summary": "Default CardReaders_GetReader 403 response",
"x-microcks-default": true,
"value": {
"error": {
"errorMessage": "Invalid or missing parameters.",
"errorCode": "BadRequest",
"details": "Validation failed for field 'storeId'."
}
}
}
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FlipdishError"
},
"examples": {
"CardReaders_GetReader500Example": {
"summary": "Default CardReaders_GetReader 500 response",
"x-microcks-default": true,
"value": {
"error": {
"errorMessage": "Invalid or missing parameters.",
"errorCode": "BadRequest",
"details": "Validation failed for field 'storeId'."
}
}
}
}
}
}
}
},
"security": [
{
"oauth2": [
"api"
]
}
],
"summary": "Flipdish Card Readers_Get Reader",
"description": "Card Readers_Get Reader via the Flipdish Open API v1.0 (GET /api/v1.0/{appId}/payments/terminals/stripe/{readerId}).",
"x-microcks-operation": {
"delay": 0,
"dispatcher": "FALLBACK"
}
}
},
"/api/v1.0/{appId}/cardreaders/kiosk/{deviceId}/bluetooth/status": {
"get": {
"tags": [
"CardReaders"
],
"operationId": "GetBluetoothTerminalStatus",
"parameters": [
{
"name": "appId",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "The app id path parameter.",
"example": "500123"
},
{
"name": "deviceId",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "The device id path parameter.",
"example": "500123"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RestApiResult_BluetoothTerminalStatus_"
},
"examples": {
"GetBluetoothTerminalStatus200Example": {
"summary": "Default GetBluetoothTerminalStatus 200 response",
"x-microcks-default": true,
"value": {
"Data": {
"SerialNumber": "string",
"SoftwareVersion": "string",
"DeviceType": "CHIPPER_2X",
"Status": "Not_Connected",
"BatteryLevel": 1.0,
"UpdateTime": "2026-06-02T12:00:00Z",
"ReaderId": "500123"
}
}
}
}
}
}
},
"400": {
"description": "BadRequest",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FlipdishError"
},
"examples": {
"GetBluetoothTerminalStatus400Example": {
"summary": "Default GetBluetoothTerminalStatus 400 response",
"x-microcks-default": true,
"value": {
"error": {
"errorMessage": "Invalid or missing parameters.",
"errorCode": "BadRequest",
"details": "Validation failed for field 'storeId'."
}
}
}
}
}
}
},
"401": {
"description": "Authentication has been denied for this request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FlipdishError"
},
"examples": {
"GetBluetoothTerminalStatus401Example": {
"summary": "Default GetBluetoothTerminalStatus 401 response",
"x-microcks-default": true,
"value": {
"error": {
"errorMessage": "Invalid or missing parameters.",
"errorCode": "BadRequest",
"details": "Validation failed for field 'storeId'."
}
}
}
}
}
}
},
"403": {
"description": "Successful authentication, but authorization has been denied for this request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FlipdishError"
},
"examples": {
"GetBluetoothTerminalStatus403Example": {
"summary": "Default GetBluetoothTerminalStatus 403 response",
"x-microcks-default": true,
"value": {
"error": {
"errorMessage": "Invalid or missing parameters.",
"errorCode": "BadRequest",
"details": "Validation failed for field 'storeId'."
}
}
}
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FlipdishError"
},
"examples": {
"GetBluetoothTerminalStatus500Example": {
"summary": "Default GetBluetoothTerminalStatus 500 response",
"x-microcks-default": true,
"value": {
"error": {
"errorMessage": "Invalid or missing parameters.",
"errorCode": "BadRequest",
"details": "Validation failed for field 'storeId'."
}
}
}
}
}
}
}
},
"security": [
{
"oauth2": [
"api"
]
}
],
"summary": "Flipdish Get Bluetooth Terminal Status",
"description": "Get Bluetooth Terminal Status via the Flipdish Open API v1.0 (GET /api/v1.0/{appId}/cardreaders/kiosk/{deviceId}/bluetooth/status).",
"x-microcks-operation": {
"delay": 0,
"dispatcher": "FALLBACK"
}
}
},
"/api/v1.0/{appId}/stripeterminal/location": {
"post": {
"tags": [
"CardReaders"
],
"operationId": "GenerateStripeTerminalLocation",
"parameters": [
{
"name": "appId",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "The app id path parameter.",
"example": "500123"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GeoPointRequest"
},
"examples": {
"GenerateStripeTerminalLocationRequestExample": {
"summary": "Default GenerateStripeTerminalLocation request",
"x-microcks-default": true,
"value": {
"Latitude": 1.0,
"Longitude": 1.0
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RestApiResult_StripeTerminalLocation_"
},
"examples": {
"GenerateStripeTerminalLocation200Example": {
"summary": "Default GenerateStripeTerminalLocation 200 response",
"x-microcks-default": true,
"value": {
"Data": {
"Location": "string"
}
}
}
}
}
}
},
"400": {
"description": "BadRequest",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FlipdishError"
},
"examples": {
"GenerateStripeTerminalLocation400Example": {
"summary": "Default GenerateStripeTerminalLocation 400 response",
"x-microcks-default": true,
"value": {
"error": {
"errorMessage": "Invalid or missing parameters.",
"errorCode": "BadRequest",
"details": "Validation failed for field 'storeId'."
}
}
}
}
}
}
},
"401": {
"description": "Authentication has been denied for this request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FlipdishError"
},
"examples": {
"GenerateStripeTerminalLocation401Example": {
"summary": "Default GenerateStripeTerminalLocation 401 response",
"x-microcks-default": true,
"value": {
"error": {
"errorMessage": "Invalid or missing parameters.",
"errorCode": "BadRequest",
"details": "Validation failed for field 'storeId'."
}
}
}
}
}
}
},
"403": {
"description": "Successful authentication, but authorization has been denied for this request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FlipdishError"
},
"examples": {
"GenerateStripeTerminalLocation403Example": {
"summary": "Default GenerateStripeTerminalLocation 403 response",
"x-microcks-default": true,
"value": {
"error": {
"errorMessage": "Invalid or missing parameters.",
"errorCode": "BadRequest",
"details": "Validation failed for field 'storeId'."
}
}
}
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FlipdishError"
},
"examples": {
"GenerateStripeTerminalLocation500Example": {
"summary": "Default GenerateStripeTerminalLocation 500 response",
"x-microcks-default": true,
"value": {
"error": {
"errorMessage": "Invalid or missing parameters.",
"errorCode": "BadRequest",
"details": "Validation failed for field 'storeId'."
}
}
}
}
}
}
}
},
"security": [
{
"oauth2": [
"api"
]
}
],
"summary": "Flipdish Generate Stripe Terminal Location",
"description": "Generate Stripe Terminal Location via the Flipdish Open API v1.0 (POST /api/v1.0/{appId}/stripeterminal/location).",
"x-microcks-operation": {
"delay": 0,
"dispatcher": "FALLBACK"
}
}
},
"/api/v1.0/{appId}/payments/terminals/stripe/register": {
"post": {
"tags": [
"CardReaders"
],
"operationId": "RegisterStripeTerminal",
"parameters": [
{
"name": "appId",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "The app id path parameter.",
"example": "500123"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CardReaderRegistrationRequest"
},
"examples": {
"RegisterStripeTerminalRequestExample": {
"summary": "Default RegisterStripeTerminal request",
"x-microcks-default": true,
"value": {
"RegistrationCode": "string",
"KioskDeviceId": "500123"
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RestApiResult_CardReader_"
},
"examples": {
"RegisterStripeTerminal200Example": {
"summary": "Default RegisterStripeTerminal 200 response",
"x-microcks-default": true,
"value": {
"Data": {
"Id": "500123",
"DeviceSoftwareVersion": "string",
"SerialNumber": "string",
"Status": "Active",
"RegistrationCode": "string",
"DeviceType": "string",
"Deleted": true,
"Action": {
"ActionState": "string",
"FailureCode": "string",
"FailureMessage": "string",
"Type": "string"
}
}
}
}
}
}
}
},
"400": {
"description": "BadRequest",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FlipdishError"
},
"examples": {
"RegisterStripeTerminal400Example": {
"summary": "Default RegisterStripeTerminal 400 response",
"x-microcks-default": true,
"value": {
"error": {
"errorMessage": "Invalid or missing parameters.",
"errorCode": "BadRequest",
"details": "Validation failed for field 'storeId'."
}
}
}
}
}
}
},
"401": {
"description": "Authentication has been denied for this request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FlipdishError"
},
"examples": {
"RegisterStripeTerminal401Example": {
"summary": "Default RegisterStripeTerminal 401 response",
"x-microcks-default": true,
"value": {
"error": {
"errorMessage": "Invalid or missing parameters.",
"errorCode": "BadRequest",
"details": "Validation failed for field 'storeId'."
}
}
}
}
}
}
},
"403": {
"description": "Successful authentication, but authorization has been denied for this request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FlipdishError"
},
"examples": {
"RegisterStripeTerminal403Example": {
"summary": "Default RegisterStripeTerminal 403 response",
"x-microcks-default": true,
"value": {
"error": {
"errorMessage": "Invalid or missing parameters.",
"errorCode": "BadRequest",
"details": "Validation failed for field 'storeId'."
}
}
}
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FlipdishError"
},
"examples": {
"RegisterStripeTerminal500Example": {
"summary": "Default RegisterStripeTerminal 500 response",
"x-microcks-default": true,
"value": {
"error": {
"errorMessage": "Invalid or missing parameters.",
"errorCode": "BadRequest",
"details": "Validation failed for field 'storeId'."
}
}
}
}
}
}
}
},
"security": [
{
"oauth2": [
"api"
]
}
],
"summary": "Flipdish Register Stripe Terminal",
"description": "Register Stripe Terminal via the Flipdish Open API v1.0 (POST /api/v1.0/{appId}/payments/terminals/stripe/register).",
"x-microcks-operation": {
"delay": 0,
"dispatcher": "FALLBACK"
}
}
},
"/api/v1.0/{appId}/payments/terminals/stripe/{readerId}/cancel_action": {
"post": {
"tags": [
"CardReaders"
],
"operationId": "CancelReaderAction",
"parameters": [
{
"name": "readerId",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "The reader id path parameter.",
"example": "500123"
},
{
"name": "appId",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "The app id path parameter.",
"example": "500123"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RestApiResult_CardReader_"
},
"examples": {
"CancelReaderAction200Example": {
"summary": "Default CancelReaderAction 200 response",
"x-microcks-default": true,
"value": {
"Data": {
"Id": "500123",
"DeviceSoftwareVersion": "string",
"SerialNumber": "string",
"Status": "Active",
"RegistrationCode": "string",
"DeviceType": "string",
"Deleted": true,
"Action": {
"ActionState": "string",
"FailureCode": "string",
"FailureMessage": "string",
"Type": "string"
}
}
}
}
}
}
}
},
"400": {
"description": "BadRequest",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FlipdishError"
},
"examples": {
"CancelReaderAction400Example": {
"summary": "Default CancelReaderAction 400 response",
"x-microcks-default": true,
"value": {
# --- truncated at 32 KB (151 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/flipdish/refs/heads/main/openapi/flipdish-devices-openapi.json