logo
Powered by Redocly

Cloudline Integration API (1.2.0)

Download OpenAPI specification:Download

E-mail: contact@cloudlineapp.com URL: http://www.cloudlineapp.com/contact Terms of Service

Welcome to the Cloudline integration API documentation

The Cloudline integration API is for industry partners to access and interact with Cloudline platform data such as making orders for our kitchen management system, generating custom menus from our Menu management system and/or custom reporting solutions.

Organizations

Operations about Organizations.

List Organizations

Gets a list of organizations you have access to based on your api key

SecurityBearer
Responses
200

Success

400

Bad Request

401

Unauthorized

403

Forbidden

500

Internal Server Error

get/organizations
Request samples 
Response samples 
application/json
[
  • {
    }
]
Sites
Operations about Sites.


List Sites
Gets a list of sites you have access to based on your api key


SecurityBearer 
Request 
query Parameters
organization_id
string
Optionally filter sites by Organization ID


 
Responses 
200
Success


400
Bad Request


401
Unauthorized


403
Forbidden


500
Internal Server Error


get/sites
Request samples 
Response samples 
application/json
[
  • {
    }
]
Activities
Operations about Site Activities.


Get Activity
Get a single activity based on its unique ID.


SecurityBearer 
Request 
path Parameters
activity_id
required
string
The unique id of the activity.


 
Responses 
200
Success


400
Bad Request


401
Unauthorized


403
Forbidden


500
Internal Server Error


get/activities/{activity_id}
Request samples 
Response samples 
application/json
{
  • "id": "1337-1337-1337-1337",
  • "name": "Relax on Cloud9",
  • "description": "Come on down to the Cloud9 Relax Zone and chill.",
  • "type": "POI",
  • "site_id": "1337-1337-1337-1337"
}
List Activities
Gets a list of activities which you have access to.


SecurityBearer 
Request 
query Parameters
site_id
string
Include site_id parameter to return activities within a particular site


 
Responses 
200
Success


400
Bad Request


401
Unauthorized


403
Forbidden


500
Internal Server Error


get/activities
Request samples 
Response samples 
application/json
[
  • {
    }
]
Orders
Operations about Orders.


Get an Order
Get a single order based on its unique ID.


SecurityBearer 
Request 
path Parameters
order_id
required
string
The unique id of the order.


 
Responses 
200
Success


400
Bad Request


401
Unauthorized


403
Forbidden


500
Internal Server Error


get/orders/{order_id}
Request samples 
Response samples 
application/json
{
  • "id": "1337-1337-1337-1337",
  • "organization_id": "1337-1337-1337-1337",
  • "site_id": "1337-1337-1337-1337",
  • "activity_id": "1337-1337-1337-1337",
  • "state": "BASKET",
  • "price": 420,
  • "fee": 42,
  • "discounted_price": 0,
  • "submitted": "2022-05-14:20:40.20Z",
  • "type": "DELIVERY",
  • "customer": {
    },
  • "items": [
    ],
  • "external_reference_id": "1337-1337-1337-1337",
  • "integration_partner_id": "1337-1337-1337-1337",
  • "integration_device_id": "1337-1337-1337-1337",
  • "integration_device_operator_id": "1337-1337-1337-1337",
  • "last_updated": "2022-05-14:20:40.20Z"
}
List Orders
Gets a list of orders from an Restaurant type Activity or across a whole Site.  


Orders can be queried for a period of up to one month at a time.  


Please be aware that querying for a large number of orders across a large number of Restaurant times will take a while if the query has not been made recently and cached.


Defaults: If no States are explicitly included or excluded then by default only COMPLETE and ARCHIVED orders will be returned.


SecurityBearer 
Request 
query Parameters
date
required
string
A date of the format YYYY-MM or YYYY-MM-DD.  YYYY-MM will return one month of orders, YYYY-MM-DD will return one day of orders.


 
activity_id
string
Return only orders for a single activity


 
istate[]
Array of strings (order-state) 
The state (or states) to include in the query response. Cannot be used in conjunction with estate.  Query parameters should be formatted as ?istate[]=COMPLETE&istate[]=ARCHIVED.


Items Enum: "BASKET" "REQUESTED" "ACCEPTED" "IN_PROGRESS" "PREPARED" "READY" "COMPLETE" "ARCHIVED"  
estate[]
Array of strings (order-state) 
The state (or states) to exclude in the query response. Cannot be used in conjuction with istate. Query parameters should be formatted as ?estate[]=BASKET&estate[]=IN_PROGRESS


Items Enum: "BASKET" "REQUESTED" "ACCEPTED" "IN_PROGRESS" "PREPARED" "READY" "COMPLETE" "ARCHIVED"  
Responses 
200
Success


400
Bad Request


401
Unauthorized


403
Forbidden


500
Internal Server Error


get/orders
Request samples 
Response samples 
application/json
[
  • {
    }
]
Create Order
Create an order which will appear in the Cloudline Kitchen Management System.


Please be aware that currently the Cloudline platform only supports Custom Order Items and does not support referencing existing menu items within the Cloudline platform.  Support for referencing menu items within the Cloudline platform will be released in an upcoming update.


This means that when creating an order you should include a list of custom_order_items as listed below in the parameters.  Any reference ID's which are included in that data will be reflected in the list Orders endpoint and can be matched up with any external ordering system's own ID's.


SecurityBearer 
Request 
Request Body schema: application/json
required
This is the order information required to create an order.


activity_id
required
string
The activity you'd like to create an order for.  Must be a Restaurant type Activity


 
type
required
string
Whether the order is for collection or delivery.  If the order is a DELIVERY then order_logistics must also be included in the request.


 Enum: "DELIVERY" "COLLECTION"  
Array of objects (order-logistic) 
 
state
required
string
This is the state of the order you'd like the order to start in.  We recommend ACCEPTED in almost all cases and is the default if this value is excluded.


 Enum: "ACCEPTED" "REQUESTED"  
integration_device_id
required
string
The ID of the device which the order was made from.


 
integration_partner_id
required
string
The ID of the integration partner.


 
external_reference_id
string
This id can be used to reference an order in an external system.


 
order_note
string
Any free text note to be associated with an order.


 
required
Array of objects (custom-order-item) 
 
Responses 
200
Success


400
Bad Request


401
Unauthorized


403
Forbidden


500
Internal Server Error


post/orders
Request samples 
application/json
{
  • "activity_id": "string",
  • "type": "DELIVERY",
  • "state": "ACCEPTED",
  • "integration_device_id": "string",
  • "integration_partner_id": "string",
  • "custom_order_items": [
    ]
}
Response samples 
application/json
{
  • "id": "1337-1337-1337-1337",
  • "organization_id": "1337-1337-1337-1337",
  • "site_id": "1337-1337-1337-1337",
  • "activity_id": "1337-1337-1337-1337",
  • "state": "BASKET",
  • "price": 420,
  • "fee": 42,
  • "discounted_price": 0,
  • "submitted": "2022-05-14:20:40.20Z",
  • "type": "DELIVERY",
  • "customer": {
    },
  • "items": [
    ],
  • "external_reference_id": "1337-1337-1337-1337",
  • "integration_partner_id": "1337-1337-1337-1337",
  • "integration_device_id": "1337-1337-1337-1337",
  • "integration_device_operator_id": "1337-1337-1337-1337",
  • "last_updated": "2022-05-14:20:40.20Z"
}
Reports
Reports matching the exports available in cl-corp.


Get reconciliation report
Returns the reconciliation report available in cl-corp, with order rows and
report-level totals. Selects the latest COMPLETE/ARCHIVED order versions with
recorded PAID/CLOUDLINE payments from ClickHouse and resolves reference data
from Postgres. API-key organisation, site and activity permissions apply.


Amounts are integer pennies and submission timestamps use RFC3339, matching
the orders API. VAT breakdowns contain numeric amounts by tax percentage.
Totals are calculated before rounding; summing rows can give different
net/VAT totals. Dates filter order submission time. Empty reports have
rows: [] and totals: null.


SecurityBearer 
Request 
query Parameters
organization_id
required
string  non-empty 
Organisation Dynamo ID, as used by the existing integration API.


 
site_id
string
Restrict the report to a site in the requested organisation.


 
activity_id
string
Restrict the report to an activity in the requested organisation/site.


 
start_date
required
string
Inclusive start. YYYY-MM-DD means the start of that local calendar day
in timezone; an RFC3339 timestamp with an offset specifies an instant.
Timestamp precision is milliseconds, matching cl-corp.


 
 Example:  start_date=2026-09-21
end_date
required
string
Inclusive end. YYYY-MM-DD means the end of that local calendar day
(23:59:59.999) in timezone; an RFC3339 timestamp with an offset specifies
an instant. Must not precede start_date.


 
 Example:  end_date=2026-09-28
timezone
string
 Default:  "UTC"
IANA timezone for calendar-day bounds. Defaults to UTC. Explicit timestamp offsets take precedence.


 
 Example:  timezone=UTC
Responses 
200
Complete reconciliation report.


400
Missing or invalid scope/date/timezone parameters.


401
Invalid or missing API key.


403
Unauthorized scope, or organisation/site/activity mismatch.


500
Report configuration, source, payload or reference lookup failed. No partial report is returned.


get/reports/reconciliation
Request samples 
Response samples 
application/json
{
  • "rows": [
    ],
  • "totals": {
    }
}
Menu
Operations about Restaurant Menus.


Get a Menu Item
Get a menu item based on its ID


SecurityBearer 
Request 
path Parameters
item
required
string
The id of the menu item that needs to be fetched


 
Responses 
200
Success


400
Bad Request


401
Unauthorized


403
Forbidden


500
Internal Server Error


get/menu-items/{item}
Request samples 
Response samples 
application/json
{
  • "id": "1asdlkfja-1asdlkfja-1asdlkfja-1asdlkfja",
  • "name": "Cloud9 Fries",
  • "price": 420
}
External Operators
Operations about External Operators.


Devices
Operations about Integrated Devices.


List Devices
Gets a list of devices which you have access to based on your api key


SecurityBearer 
Request 
query Parameters
partner_id
required
string
Your Partner ID


 
Responses 
200
Success


400
Bad Request


401
Unauthorized


403
Forbidden


500
Internal Server Error


get/devices
Request samples 
Response samples 
application/json
[
  • {
    }
]
Create Device
Creates a new device.  The device ID can then be used to interact with the Cloudline platform.  Platform devices are used to trace the origin of a request primarily for debugging and logging purposes.  


A good example of this is tracking a Create Order request back to the Till or POS device which performed the transaction.


SecurityBearer 
Request 
Request Body schema: application/json
required
This is the information required to create a device.


name
required
string
A human identifiable name for the device.


 
partner_id
required
string
Your integration partner ID.


 
description
string
A more detailed descriptionof the device if required.


 
external_id
string
An external ID which can be used to reference the device in other systems.


 
Responses 
200
Success


400
Bad Request


401
Unauthorized


403
Forbidden


500
Internal Server Error


post/devices
Request samples 
application/json
{
  • "name": "Till 42",
  • "partner_id": "1337-1337-1337-1337",
  • "description": "Till number 42 located in the play barn.",
  • "external_id": "4242-4242-4242-4242"
}
Response samples 
application/json
{
  • "id": "1337-1337-1337-1337",
  • "name": "Till 42",
  • "description": "Till number 42 located in the play barn.",
  • "external_id": "4242-4242-4242-4242",
  • "partner_id": "4242-4242-4242-4242"
}