Introduction
Welcome to the CloudWaitress API documentation. Contact us if you have any questions
Authentication
To authorize, use this code:
curl https://api.cloudwaitress.com/v1/...
-H "Authorization: YOUR_API_KEY"
Make sure to replace
YOUR_API_KEYwith your API key.
CloudWaitress uses API keys to allow access to the API. Register a new API key under your restaurant settings.
CloudWaitress expects for the API key to be included in all API requests to the server in a header that looks like the following:
Ratelimit
There is a limit of 60 requests in a 60 second period. After 60 seconds has passed, your limit will be reset.
The following headers will be present in each response and will indicate your rate limit details
| Header | Description |
|---|---|
| X-Rate-Limit-Limit | The number of API requests per 60 seconds allowed |
| X-Rate-Limit-Remaining | The number of API requests you have remaining for this 60 second period |
| X-Rate-Limit-Expiry | The unix timestamp (milliseconds) at which the current 60 second period will expire |
Response Format
Success response, will contain additional fields relating to request
{
"outcome": 0
}
Error response with message key for description
{
"outcome": 1,
"message": "Error message"
}
All responses follow a standardised JSON format. The "outcome" key indicates whether the operation was a success.
If the "outcome" is 0, the operation is successful and the response will contain additional data relating to the request.
If the "outcome" is 1, it indicates an error occurred. The "message" key will provide a description of the error.
Order Model
Base Object
| Field | Description |
|---|---|
| _id | The unique ID of the object |
| created | A unix timestamp of the order creation time (milliseconds) |
| restaurant_id | The unique ID of the restaurant associated with the order |
| organisation_id | The unique ID of the organisation associated with the order |
| number | The order number as shown to the customer and restaurant staff |
| status | The status of the order, can be unconfirmed, confirmed, ready, on_route, complete |
| notes | Any order notes as entered by the customer |
| bill | See OrderBill object |
| payment | See OrderPayment object |
| customer | See OrderCustomer object |
| promos | See OrderPromo object. Contains an array of the OrderPromo object |
| dishes | See OrderDish object. Contains an array of the OrderDish object |
| config | See OrderConfig object |
| ready_in | See OrderReadyIn object. This field optional and may be undefined depending on the restaurants settings |
| delivery_in | See OrderDeliveryIn object. This field optional and may be undefined depending on the restaurants settings |
OrderBill
Represents the order totals as shown to the customer
| Field | Type | Description |
|---|---|---|
| currency | string | 3 letter code currency of the bill |
| total | number | Total order value as number |
| total_cents | number | Total order value in cents |
| cart | number | Total value of the customers cart |
| discount | number | Total value of any discount that has been applied |
| taxes | OrderTax | Contains an array of OrderTax objects |
| tax_in_prices | boolean | Indicates whether the prices include tax or whether tax has been added onto the cart total |
| fees | OrderFee | Contains an array of OrderFee objects |
OrderFee
Represents a fee that may be added to the customers cart based on certain conditions
| Field | Type | Description |
|---|---|---|
| _id | string | Unique ID of the fee |
| name | string | The display name |
| fixed_value | number | The fixed value of this fee |
| percent_value | number | The percentage value of this fee |
| value | number | The final value of this fee which is added to the customers cart |
| is_payment_fee | boolean | Indicates if this fee is due to a payment based condition |
| voided | boolean | Indicates whether this fee has been voided |
OrderTax
Represents the order totals as shown to the customer
| Field | Type | Description |
|---|---|---|
| _id | string | Unique ID of the tax |
| name | string | The display name of this tax |
| rate | number | The % value of this tax, 10% is simply the value 10 |
| compound | boolean | Whether this tax value should compound with order taxes |
| amount | number | The value of this tax in the customers bill |
OrderPayment
Represents the payment details relating to an order
| Field | Type | Description |
|---|---|---|
| method | string | cash, card, stripe, paypal, paygate_payweb, poli_pay, ipay88, bambora_apac |
| currency | string | The final payment currency, may be different if an online payment processor is used |
| total | number | The final payment total |
| total_cents | number | The final payment total in cents |
| status | string | success, pending, error |
| reference | string | The reference payment ID as returned by a payment processor |
| reference_status | string | The reference payment status as returned by a payment processor |
| error | string | The error description if an error occurred with the payment |
OrderCustomer
Represents the customer details relating to the order
| Field | Type | Description |
|---|---|---|
| _id | string | Unique customer ID |
| name | string | Name as entered by the customer |
| phone | string | Phone number entered by the customer |
| string | Email entered by the customer |
OrderPromos
Represents the payment details relating to the order
| Field | Type | Description |
|---|---|---|
| _id | string | Unique ID of this promo |
| name | string | Display name |
| code | string | The code entered by a customer to redeem this promo |
| fixed_discount | number | Fixed discount value of the promo |
| percent_discount | number | Percentage discount value of the promo |
| min_order | number / "" | Minimum cart order required |
| max_uses | number / "" | Maximum total uses allowed by this promo |
| auto_apply | boolean | Is this promo automatically applied if possible |
| once_per_customer | boolean | Indicates promo limited to one use per customer |
| logged_in_only | boolean | Indicates promo is only for customers who are registered |
| valid_times | Array<{ "start": number, "end": number }> | Array of objects containing the keys start and end. Each of this has a unix timestamp (milliseconds) indicating the valid periods of this promo |
| disabled | boolean | Indicates whether promo has been disabled by the restaurant |
OrderDishes
Line items as shown to the customer
| Field | Type | Description |
|---|---|---|
| _id | string | Unique ID of this dish |
| menu_id | string | Unique ID of the menu |
| category_id | string | Unique ID of the dish category |
| name | string | Dish name |
| display_name | string | Display name. Overrides dish name if set. |
| qty | number | Dish quantity |
| price | number | Dish total price |
| subtitle | string | Dish subtitle from menu |
| tags | string[] | IDs of dish tags |
| status | string | Availability status (experimental). Values: null (default), 'no-stock', 'not-available', 'hidden' |
| ingredients | DishIngredient[] | Total value of any discount that has been applied |
| option_sets | OptionSet[] | Contains an array of OrderTax objects |
DishIngredient
Specifies whether the ingredient should be included or excluded
| Field | Type | Description |
|---|---|---|
| _id | string | Unique ID of this ingredient |
| name | string | Name of the ingredient |
| active | boolean | True to include. False to exclude. Default to true. |
OptionSet
Dish modifiers or choices to be added to the dish
| Field | Type | Description |
|---|---|---|
| _id | string | Unique ID of this option set |
| name | string | Name of the option set |
| display_name | boolean | If set, it displays instead of name |
| conditions | OptionSetConditions | Rules for applying this option set into the dish |
| options | OptionSetOption[] | Selected options |
OptionSetConditions
Option set rules
| Field | Type | Description |
|---|---|---|
| required | boolean | Option set is required to be specified |
| multi_select | boolean | Allows to select multiple options. |
| quantity_select | boolean | Allows quantity to be set. Otherwise, on/off only. |
| min_options | boolean | Minimum number of selected options. |
| max_options | boolean | Maximum number of selected options. |
| free_amount | number | Free quantity before charging. |
OptionSetOption
Selected option
| Field | Type | Description |
|---|---|---|
| _id | string | Unique ID of this option |
| name | string | Option name |
| quantity | number | Specified quantity |
| price | number | Price of the option |
| status | string | Availability status (experimental). Values: null (default), 'no-stock', 'not-available', 'hidden' |
Order API
Get Orders
curl https://api.cloudwaitress.com/v1/orders \
-X POST \
-H "Content-Type: application/json" \
-H "Authorization: YOUR_API_KEY" \
-d `
{
"restaurant_id": "xxxxxxx",
"limit": 10,
"page": 1,
"sort": { "created": -1 },
}
`
Returns
{
"outcome": 0,
"count": 90,
"items": [
{
"_id": "123",
"notes": "",
"created": 1553398645547,
"updated": null,
"restaurant_id": "123",
"organisation_id": "123",
"status": "unconfirmed",
"number": 200,
"bill": {
"currency": "USD",
"total": 10,
"total_cents": 1000,
"cart": 10,
"discount": 0,
"taxes": [
{
"_id": "123",
"name": "GST",
"rate": 10,
"compound": false,
"amount": 0.91
}
],
"tax_in_prices": true,
"fees": []
},
"payment": {
"method": "cash",
"currency": "USD",
"total": 10,
"total_cents": 1000,
"status": "success",
"reference": null,
"reference_status": null,
"error": null
},
"customer": {
"_id": "123",
"name": "John Doe",
"phone": "1234 1234",
"email": "name@example.com"
},
"promos": [],
"dishes": [
{
"_id" : "H1x3H2LZV",
"type" : "standard",
"menu_id" : "rJMFG38ZN",
"category_id" : "BJb0Z3IbN",
"name" : "Hawaiian",
"display_name" : "",
"price" : 6,
"subtitle" : "",
"tags" : [],
"status" : null,
"ingredients" : [
{
"_id" : "rkjKBnU-N",
"name" : "Tomato Base",
"active" : true
},
{
"_id" : "HkOcB3U-4",
"name" : "Ham",
"active" : true
},
{
"_id" : "SkCqB3UZV",
"name" : "Pineapple",
"active" : true
},
{
"_id" : "B1FornIWN",
"name" : "Cheese",
"active" : true
}
],
"option_sets" : [
{
"_id" : "SkQoU2UbV",
"name" : "Base Choice",
"display_name" : "",
"conditions" : {
"required" : true,
"multi_select" : false,
"quantity_select" : false,
"min_options" : 1,
"max_options" : "",
"free_amount" : ""
},
"options" : [
{
"_id" : "2y53KyrXg",
"name" : "Gluten Free",
"price" : "4.0",
"quantity" : 1
}
]
},
{
"_id" : "rJI3G4uZV",
"name" : "Extra Toppings",
"display_name" : "",
"conditions" : {
"required" : false,
"multi_select" : true,
"quantity_select" : false,
"min_options" : 1,
"max_options" : "",
"free_amount" : ""
},
"options" : [
]
},
{
"_id" : "-ef37By_T",
"name" : "Extra Swirls / Sauces",
"display_name" : "",
"conditions" : {
"required" : false,
"multi_select" : true,
"quantity_select" : false,
"min_options" : "",
"max_options" : "",
"free_amount" : ""
},
"options" : [
]
}
],
"price_type" : "standard",
"choices" : [
],
"qty" : 1,
"notes" : ""
}.
{
"type": "standard",
"_id": "GiZ4U5MeOy",
"menu_id": "jvfMUwpwU",
"category_id": "ejyil1ojkF",
"name": "Pepperoni",
"display_name": "",
"price": 16,
"subtitle": "",
"tags": [
"2AWPEHB1w"
],
"status": null,
"ingredients": [
{
"_id": "SJerI3IW4",
"name": "Cheese",
"active": true
},
{
"_id": "ry_SU38-V",
"name": "Pepperoni",
"active": true
}
],
"option_sets": [
{
"_id": "ufS0palSt",
"name": "Pizza Menu - Base Choice",
"display_name": "Base Choice",
"conditions": {
"required": true,
"multi_select": false,
"quantity_select": false,
"min_options": "",
"max_options": "",
"free_amount": ""
},
"options": [
{
"_id": "4Ajq7XMq9R",
"name": "Stuffed Crust",
"quantity": 1,
"price": "4.0",
"status": null
}
]
},
{
"_id": "oJzT9LW5W",
"name": "Pizza Option Sets - Variable with Points",
"display_name": "Extra Toppings",
"conditions": {
"required": false,
"multi_select": true,
"quantity_select": false,
"min_options": "",
"max_options": "",
"free_amount": ""
},
"options": [],
"using_points": true,
"variable_price_ref": "ufS0palSt"
}
],
"price_type": "standard",
"choices": [],
"option_set_primary": "",
"taxes": [],
"total_points": 8,
"qty": 2,
"notes": "Normal Pizza Dish"
},
{
"type": "standard",
"_id": "Lz6dVjf_Ay",
"menu_id": "jvfMUwpwU",
"category_id": "ejyil1ojkF",
"name": "Veggie",
"display_name": "",
"price": 24.9,
"subtitle": "",
"tags": [
"2hH8bLjhK"
],
"status": null,
"ingredients": [
{
"_id": "ryx0Ph8-N",
"name": "Tomato Base",
"active": true
},
{
"_id": "SkKAw2U-V",
"name": "Onion",
"active": true
},
{
"_id": "r1lkO2U-4",
"name": "Pineapple",
"active": true
},
{
"_id": "B15Juh8bE",
"name": "Capsicum",
"active": false
},
{
"_id": "ByExun8bE",
"name": "Cheese",
"active": true
}
],
"option_sets": [
{
"_id": "ufS0palSt",
"name": "Pizza Menu - Base Choice",
"display_name": "Base Choice",
"conditions": {
"required": true,
"multi_select": false,
"quantity_select": false,
"min_options": "",
"max_options": "",
"free_amount": ""
},
"options": [
{
"_id": "TpazBCJtQj",
"name": "Classic",
"quantity": 1,
"price": "",
"status": null
}
],
"freeOptions": []
},
{
"_id": "oJzT9LW5W",
"name": "Pizza Option Sets - Variable with Points",
"display_name": "Extra Toppings",
"conditions": {
"required": false,
"multi_select": true,
"quantity_select": false,
"min_options": "",
"max_options": "",
"free_amount": ""
},
"options": [
{
"_id": "nh3KXPNoY",
"name": "Pepperoni",
"price": {
"whole": {
"points": 3
}
},
"quantity": 1,
"prices": {
"TpazBCJtQj": {
"whole": {
"points": 3,
"single": 3,
"double": 6
},
"half": {
"points": 1.5,
"single": 1.5,
"double": 3
}
}
},
"quantity_multiplier_price": "single",
"position": "whole",
"quantity_multiplier": "single"
},
{
"_id": "ZesOPKy5ar",
"name": "Salami",
"price": {
"whole": {
"points": 3
}
},
"quantity": 1,
"prices": {
"TpazBCJtQj": {
"whole": {
"points": 3,
"single": 3,
"double": 6
},
"half": {
"points": 1.5,
"single": 1.5,
"double": 3
}
}
},
"quantity_multiplier_price": "double",
"position": "whole",
"quantity_multiplier": "double"
},
{
"_id": "HFdEDkRvpl",
"name": "Mozzarella",
"price": {
"whole": {
"points": 2
}
},
"quantity": 1,
"prices": {
"TpazBCJtQj": {
"whole": {
"points": 2,
"single": 2,
"double": 4
},
"half": {
"points": 1,
"single": 1,
"double": 2
}
}
},
"position": "right",
"quantity_multiplier": "single",
"quantity_multiplier_price": "single"
},
{
"_id": "AimUU22be",
"name": "Capsicum",
"price": {
"whole": {
"points": 1
}
},
"quantity": 1,
"prices": {
"TpazBCJtQj": {
"whole": {
"points": 1,
"single": 1,
"double": 2
},
"half": {
"points": 0.5,
"single": 0.5,
"double": 1
}
}
},
"position": "left",
"quantity_multiplier": "single",
"quantity_multiplier_price": "single"
},
{
"_id": "YYJ4JkeYL",
"name": "Onions",
"price": {
"whole": {
"points": 1
}
},
"quantity": 1,
"prices": {
"TpazBCJtQj": {
"whole": {
"points": 1,
"single": 1,
"double": 2
},
"half": {
"points": 0.5,
"single": 0.5,
"double": 1
}
}
},
"position": "left",
"quantity_multiplier": "single"
},
{
"_id": "TWUiFxQ4Zp",
"name": "Mushrooms",
"price": {
"whole": {
"points": 2
}
},
"quantity": 1,
"prices": {
"TpazBCJtQj": {
"whole": {
"points": 2,
"single": 2,
"double": 4
},
"half": {
"points": 1,
"single": 1,
"double": 2
}
}
},
"position": "right",
"quantity_multiplier": "single"
}
],
"using_points": true,
"variable_price_ref": "ufS0palSt",
"freeOptions": []
}
],
"price_type": "standard",
"choices": [],
"taxes": [],
"qty": 1,
"notes": "Pizza with Points OptionSet"
},
{
"type": "combo",
"_id": "OMd-sVAMB",
"menu_id": "jvfMUwpwU",
"category_id": "fpOxo0IxL",
"name": "2 Pizzas with Points",
"display_name": "",
"subtitle": "",
"price": 26,
"tags": [],
"status": null,
"ingredients": [],
"option_sets": [],
"choices": [
{
"_id": "6sfIXRGsW",
"name": "1st Pizza",
"selected": {
"type": "standard",
"_id": "GiZ4U5MeOy",
"menu_id": "jvfMUwpwU",
"category_id": "ejyil1ojkF",
"name": "Pepperoni",
"display_name": "",
"price": 4,
"description": "Loaded with pepperonis and cheese on a tomato base",
"subtitle": "",
"image": {
"_id": "6f1e43bd-a365-46d7-9a86-063089271edd",
"name": "pizza-pepperoni-600-400.jpeg"
},
"tags": [
"2AWPEHB1w"
],
"status": null,
"ingredients": [
{
"_id": "SJerI3IW4",
"name": "Cheese",
"active": true
},
{
"_id": "ry_SU38-V",
"name": "Pepperoni",
"active": true
}
],
"option_sets": [
{
"_id": "ufS0palSt",
"name": "Pizza Menu - Base Choice",
"display_name": "Base Choice",
"conditions": {
"required": true,
"multi_select": false,
"quantity_select": false,
"min_options": "",
"max_options": "",
"free_amount": ""
},
"options": [
{
"_id": "TpazBCJtQj",
"name": "Classic",
"quantity": 1,
"price": "",
"status": null
}
],
"freeOptions": []
},
{
"_id": "oJzT9LW5W",
"name": "Pizza Option Sets - Variable with Points",
"display_name": "Extra Toppings",
"conditions": {
"required": false,
"multi_select": true,
"quantity_select": false,
"min_options": "",
"max_options": "",
"free_amount": ""
},
"options": [
{
"_id": "nh3KXPNoY",
"name": "Pepperoni",
"price": {
"whole": {
"points": 3
}
},
"quantity": 1,
"prices": {
"TpazBCJtQj": {
"whole": {
"points": 3,
"single": 3,
"double": 6
},
"half": {
"points": 1.5,
"single": 1.5,
"double": 3
}
}
},
"position": "whole",
"quantity_multiplier": "single",
"quantity_multiplier_price": "single"
},
{
"_id": "HFdEDkRvpl",
"name": "Mozzarella",
"price": {
"whole": {
"points": 2
}
},
"quantity": 1,
"prices": {
"TpazBCJtQj": {
"whole": {
"points": 2,
"single": 2,
"double": 4
},
"half": {
"points": 1,
"single": 1,
"double": 2
}
}
},
"position": "right",
"quantity_multiplier": "double"
},
{
"_id": "AimUU22be",
"name": "Capsicum",
"price": {
"whole": {
"points": 1
}
},
"quantity": 1,
"prices": {
"TpazBCJtQj": {
"whole": {
"points": 1,
"single": 1,
"double": 2
},
"half": {
"points": 0.5,
"single": 0.5,
"double": 1
}
}
},
"position": "left",
"quantity_multiplier": "double"
},
{
"_id": "YYJ4JkeYL",
"name": "Onions",
"price": {
"whole": {
"points": 1
}
},
"quantity": 1,
"prices": {
"TpazBCJtQj": {
"whole": {
"points": 1,
"single": 1,
"double": 2
},
"half": {
"points": 0.5,
"single": 0.5,
"double": 1
}
}
},
"position": "whole",
"quantity_multiplier": "single"
}
],
"using_points": true,
"variable_price_ref": "ufS0palSt",
"freeOptions": [
"YYJ4JkeYL",
"AimUU22be",
"HFdEDkRvpl"
]
}
],
"price_type": "standard",
"choices": [],
"option_set_primary": "",
"taxes": [],
"total_points": 8,
"qty": 1,
"notes": ""
},
"lpo": 0.9
},
{
"_id": "9fD3UYC6S",
"name": "2nd Pizza",
"selected": {
"type": "standard",
"_id": "Lz6dVjf_Ay",
"menu_id": "jvfMUwpwU",
"category_id": "ejyil1ojkF",
"name": "Veggie",
"display_name": "",
"price": 12.9,
"description": "Tomato and onion with light herb seasoning",
"subtitle": "",
"image": {
"_id": "4b533707-09ea-4e54-8db5-2dd2ba05a1f2",
"name": "veggie-pizza-600-400.jpeg"
},
"tags": [
"2hH8bLjhK"
],
"status": null,
"ingredients": [
{
"_id": "ryx0Ph8-N",
"name": "Tomato Base",
"active": true
},
{
"_id": "SkKAw2U-V",
"name": "Onion",
"active": true
},
{
"_id": "r1lkO2U-4",
"name": "Pineapple",
"active": true
},
{
"_id": "B15Juh8bE",
"name": "Capsicum",
"active": true
},
{
"_id": "ByExun8bE",
"name": "Cheese",
"active": true
}
],
"option_sets": [
{
"_id": "ufS0palSt",
"name": "Pizza Menu - Base Choice",
"display_name": "Base Choice",
"conditions": {
"required": true,
"multi_select": false,
"quantity_select": false,
"min_options": "",
"max_options": "",
"free_amount": ""
},
"options": [
{
"_id": "TpazBCJtQj",
"name": "Classic",
"quantity": 1,
"price": "",
"status": null
}
],
"freeOptions": []
},
{
"_id": "oJzT9LW5W",
"name": "Pizza Option Sets - Variable with Points",
"display_name": "Extra Toppings",
"conditions": {
"required": false,
"multi_select": true,
"quantity_select": false,
"min_options": "",
"max_options": "",
"free_amount": ""
},
"options": [
{
"_id": "nh3KXPNoY",
"name": "Pepperoni",
"price": {
"whole": {
"points": 3
}
},
"quantity": 1,
"prices": {
"TpazBCJtQj": {
"whole": {
"points": 3,
"single": 3,
"double": 6
},
"half": {
"points": 1.5,
"single": 1.5,
"double": 3
}
}
},
"position": "whole",
"quantity_multiplier": "single",
"quantity_multiplier_price": "single"
},
{
"_id": "HFdEDkRvpl",
"name": "Mozzarella",
"price": {
"whole": {
"points": 2
}
},
"quantity": 1,
"prices": {
"TpazBCJtQj": {
"whole": {
"points": 2,
"single": 2,
"double": 4
},
"half": {
"points": 1,
"single": 1,
"double": 2
}
}
},
"position": "whole",
"quantity_multiplier": "single"
}
],
"using_points": true,
"variable_price_ref": "ufS0palSt",
"freeOptions": [
"HFdEDkRvpl"
]
}
],
"price_type": "standard",
"choices": [],
"taxes": [],
"qty": 1,
"notes": ""
},
"lpo": 0.9
}
],
"price_type": "standard",
"taxes": [
"zxiiTOmGm"
],
"total_points": 8,
"qty": 1,
"notes": "Pizza with Points and Excess"
}
],
"config": {
"service" : "pickup",
"due" : "later",
"date" : "2019-03-11",
"time" : "08:30",
"destination" : "",
"destination_misc" : "",
"lat" : 0,
"lng" : 0,
"distance" : -1,
"driving_time" : -1,
"zone" : "",
"table" : "",
"table_id" : "",
"table_password" : "",
"number_of_people" : "",
"confirmed" : true
},
"ready_in": {
"timestamp": 1553398891787
},
"delivery_in": {
"timestamp": 1553398891787
}
}
],
"web_url": "https://myrestaurant.cloudwaitress.com/order/123"
}
This endpoint will retrieve all your orders
HTTP Request
POST https://api.cloudwaitress.com/v1/orders
Request Parameters
| Key | Required | Description |
|---|---|---|
| restaurant_id | yes | The ID of the restaurant to query orders from |
| limit | yes | The number of orders to include in the request. Maximum is 20 |
| page | yes | Specifies which page of orders to retrieve. A value of 1 with the limit 10 will return the first 10 orders based on the sort value. A value of 2 will return orders 10-20. |
| sort | yes | Species how the orders will be sorted. The value to {"created": -1} sorts orders from new to old. A value of {"created": 1} will sort the orders from old to new. |
Response Parameters
| Key | Type | Description |
|---|---|---|
| count | number | The total amount of orders available to query from |
| items | Order[] | List of orders based on request limit, page and sort. See order model for details |
Update Order Status
curl https://api.cloudwaitress.com/v1/order/update-status \
-X POST \
-H "Content-Type: application/json" \
-H "Authorization: YOUR_API_KEY" \
-d `
{
"restaurant_id": "xxxxxxx",
"order_id": "yyyyyyy",
"status": "unconfirmed|awaiting_payment|confirmed|ready|on_route|complete|cancelled",
}
`
Returns (Successful)
{
"outcome": 1,
"restaurant_id": "xxxxxxx",
"order_id": "yyyyyyy",
"status": "ready"
}
Returns (Failure - Order not found)
{
"outcome": 1,
"message": "Update status failed. Order not found."
}
Returns (Failure - Same status)
{
"outcome": 1,
"message": "Update status failed. Validation failed. Current and future statuses are the same."
}
Returns (Failure - Generic)
{
"outcome": 1,
"message": "Update status failed."
}
This endpoint will change the order status.
HTTP Request
POST https://api.cloudwaitress.com/v1/order/update-status
Request Parameters
| Key | Required | Description |
|---|---|---|
| restaurant_id | yes | The ID of the restaurant where the order was placed. |
| order_id | yes | The ID of the order. |
| status | yes | The new status of the order. |
Response Parameters
| Key | Type | Description |
|---|---|---|
| outcome | number | 0 for successful execution; 1 for a failure. |
| message | string | Present when outcome is equal to 1. May show the cause of failure. |
| restaurant_id | string | The ID of the restaurant where the order was placed. |
| order_id | string | The ID of the updated order. |
| status | string | The new status of the order. |
Update Order Status to On Route
curl https://api.cloudwaitress.com/v1/order/update-on-route \
-X POST \
-H "Content-Type: application/json" \
-H "Authorization: YOUR_API_KEY" \
-d `
{
"restaurant_id": "xxxxxxx",
"order_id": "yyyyyyy",
}
`
Returns (Successful)
{
"outcome": 1,
"restaurant_id": "xxxxxxx",
"order_id": "yyyyyyy",
"status": "on_route"
}
Returns (Failure - Order is not ready)
{
"outcome": 1,
"message": "Update status failed. Validation failed. Unexpected status sequence: confirmed --> on_route."
}
Returns (Failure - Generic)
{
"outcome": 1,
"message": "Update status failed."
}
This endpoint will change the order status to On Route.
HTTP Request
POST https://api.cloudwaitress.com/v1/order/update-on-route
Request Parameters
| Key | Required | Description |
|---|---|---|
| restaurant_id | yes | The ID of the restaurant where the order was placed. |
| order_id | yes | The ID of the order. |
Response Parameters
| Key | Type | Description |
|---|---|---|
| outcome | number | 0 for successful execution; 1 for a failure. |
| message | string | Present when outcome is equal to 1. May show the cause of failure. |
| restaurant_id | string | The ID of the restaurant where the order was placed. |
| order_id | string | The ID of the updated order. |
| status | string | The new status of the order. |
Update Order Status to Delivered
curl https://api.cloudwaitress.com/v1/order/update-delivered \
-X POST \
-H "Content-Type: application/json" \
-H "Authorization: YOUR_API_KEY" \
-d `
{
"restaurant_id": "xxxxxxx",
"order_id": "yyyyyyy",
}
`
Returns (Successful)
{
"outcome": 1,
"restaurant_id": "xxxxxxx",
"order_id": "yyyyyyy",
"status": "complete"
}
Returns (Failure - Order is not On Route)
{
"outcome": 1,
"message": "Update status failed. Validation failed. Unexpected status sequence: confirmed --> completed."
}
Returns (Failure - Generic)
{
"outcome": 1,
"message": "Update status failed."
}
This endpoint will change the order status to Complete.
HTTP Request
POST https://api.cloudwaitress.com/v1/order/update-delivered
Request Parameters
| Key | Required | Description |
|---|---|---|
| restaurant_id | yes | The ID of the restaurant where the order was placed. |
| order_id | yes | The ID of the order. |
Response Parameters
| Key | Type | Description |
|---|---|---|
| outcome | number | 0 for successful execution; 1 for a failure. |
| message | string | Present when outcome is equal to 1. May show the cause of failure. |
| restaurant_id | string | The ID of the restaurant where the order was placed. |
| order_id | string | The ID of the updated order. |
| status | string | The new status of the order. |
Webhooks
Webhooks are used to receive system events via a HTTPS request. In the admin dashboard, you can create webhooks under your restaurant settings.
When creating a webhook, you my specify a HTTPS endpoint that will be notified when an event occurs.
Your HTTPS endpoint will be called via POST request and will contain data in JSON format.
For data security reasons, your endpoint must use https:// security, otherwise it will not be called
Webhook Object
The data sent to your webhook will be a JSON object with the following properties
{
"secret": "47a7868c-3d9c-4934-a4b7-e2790074a93b",
"event": "order_new",
"event_id": "WPHr9a0r4B-ePQBTadzWs",
"restaurant_id": "BaePHWr9a0B5Tadzr4QsK",
"data": {}
}
| Key | Type | Description |
|---|---|---|
| secret | string | Your webhook secret key that is used to validate the origin of the request |
| event | string | The name of the event that triggered the webhook. See event types below |
| event_id | string | A unique ID for the event. Can be used as an idempotency key to ensure events aren't processed twice |
| restaurant_id | string | The restaurant ID that owns this event and webhook |
| data | object | The data supplied for the event, see event types below for what data is included with each event |
Processing Event & Verifying Secret
// Node.js express server example
const express = require('express')
const bodyParser = require('body-parser')
const app = express()
const port = 3000
const mySecretKey = "..."
app.use(bodyParser.json())
app.post('/webhook-path', (request, response) => {
const data = request.body;
// CHECK SECRET KEY
if (data.secret !== mySecretKey) {
return res.end()
}
// PROCESS EVENT HERE & SEND OK RESPONSE
response.send("OK")
})
app.listen(port, () => console.log(`Server listening on port ${port}`))
Be sure to validate the origin of the webhook request using the secret key sent in the request. You can use this to perform a equality comparison against the secret key provided in the admin dashboard. If the secret does not match, you should not process the event.
Event Types
| Event Name | Data Provided | Description |
|---|---|---|
| order_new | order, customer | Triggered when a new order is placed |
| order_update_status | order, customer | Triggered when an order's status has been updated |
| order_update_ready_time | order, customer | Triggered when an order's ready time has been updated |
| booking_new | booking, customer | Triggered when a new booking is placed |
| booking_update_status | booking, customer | Triggered when a booking's status has been updated |
Re-try Behavior
If your webhook fails due to one of the following circumstances:
- Could not connect to your endpoint
- Receives an error status code from your endpoint
The webhook service will make 3 additional attempts to resend the event. There will be a 30 second delay between each attempt.
If all attempts fail, the webhook event will be dropped.
Errors
The CloudWaitress API uses the following error codes:
| Error Code | Meaning |
|---|---|
| 400 | Bad Request -- Your request is invalid |
| 401 | Unauthorized -- Your API key is wrong |
| 404 | Not Found -- This requested route is not found |
| 429 | Too Many Requests -- You have exceeded your ratelimit |
| 500 | Internal Server Error -- We had a problem with our server. Try again later |