Online Delivery Provider API Documentation

Online Delivery Provider Docs
Overview
General Guides
Getting Started
API General Definitions
API Authentication/Authorization
Webhook
API Usage Limits
Error Responses
Authentication
Scopes
Generate Token
Usage
Orders Integrations
Overview
Operations
Integration Flows
Orders Endpoints
Create Order
Update Order
Update Order Status
Update Customer Payment
Update Order Delivery Information
PUT /v1/orders/{orderId}/delivery
Models
Menus Integration
Overview
Operations
Integration Flows
Menu Events And Callbacks
Menu Publish
Update Menu Entities Availability
Send Menu
Upsert Hours
Callback Errors
Models
How to Send Test Webhooks
Storefront Integration
Overview
Operations
Integration Flows
Storefront Events And Callbacks
Get store availability
Pause store
Unpause store
Models
Overview
The API endpoints are developed around RESTful principles secure via the OAuth2.0 protocol.
Beyond the entry points, the API also provides a line of communication into your system via webhooks.
For testing purposes, we offer a staging environment.
General Guides
Getting Started
Onboard your application
Onboard your webhook configurations
Onboard your store(s)
OAuth2.0
Request Examples
URL Encode Form
HTTP Basic Auth
Webhook
Notification Schema
Notification Request Example
Expected Response
Webhook Auth
API Usage Limits
Error Responses
Getting Started
Onboard your application
External developers are required to have a registered Application representing their integration. This is a one-time, manual registration needed to
setup authentication and authorization between your application and the API. Please reach out to your Account Representative to register your
Application with the API.
Once onboarded, your Application will receive its own Application ID and Client Secret for each environment (production and staging).
This Guide will walk you through where and how to use these credentials.
Your Account Representative will send the two credentials to you.
NOTE: The Application ID used to be called the Partner ID, so please use those interchangeably.
Onboard your webhook configurations
The API allows you to configure your integration to receive Webhook into your system. Please reach out to your Account Representative to
register to receive Webhooks from the API.
Onboard your store(s)
Applications are required to register every store to authorize requests at a store level. This registration is on a per-store basis, as to associate the
store entity in your system with the store entity in our system. After a store is onboarded, its ID will be used in every request in header X-Store-
Id. Reach out to your Account representative to onboard each store that your application acts on behalf of.
The APIs use resource-oriented URLs communicating, primarily, via JSON and leveraging the HTTP headers, response status codes, and verbs.
To exemplify how the API is to be consumed, consider a fake GET resource endpoint invocation below:
curl --request GET 'https://partners-staging.api.com/v1/resource/123' \

--header 'Authorization: Bearer 34fdabeeafds=' --header 'X-Store-Id:
321' --header 'X-Application-Id: e22f94b3-967c-4e26-bf39-9e364066b68b'
Header Description
Authorization Standard HTTP header is used to associate the request with the originating invoker. The content of this
header is a Bearer token generated from you client_secret, defined in the API Auth guide.
X-Application-Id The plain-text Application Id, provided at onboarding.
X-Store-Id The ID of the store in your system this call acts on behalf of, available after a store onboarding.
All resource endpoints expect the Authorization and X-Application-Id header, the remaining headers are explicitly stated in the
individual endpoint documentation section.
With these headers, the system will:
Validate the client token, making sure the call is originating from a trusted source.
Validate that the Application has the permission to access the v1/resource/{id} resource via the Application's pre-configured scopes.
Translate your X-Store-Id to our internal store ID (e.g. AAA).
Validate and retrieve resource AAA, that is associated to your Application via store id 321.
POST/PUT methods will look similiar to the GET calls, but they'll take in a body in the HTTP request (default to the application/json content-type).
curl --location --request POST 'https://partners-staging.api.com/v1
/resource' \
--header 'Authorization: Bearer 34fdabeeafds=' --header 'X-Store-Id:
321' --header 'X-Application-Id: e22f94b3-967c-4e26-bf39-9e364066b68b"
--data '{"foo": "bar"}'
OAuth2.0
The Authorization API is based on the OAuth2.0 protocol, using the client credentials grant. Resources expect a valid token sent as a Bearer to
ken in the HTTP Authorization header.
To generate the token, use the Application ID and Client Secret (provided during onboarding) to the Token Auth endpoint endpoint. The
result of this invocation is a token that is valid for a pre-determined time or until it is manually revoked.
The response of the following endpoints will return a token that will be sent as a Bearer value of the Authorization HTTP header, along with
meta information such as expiry-date.
Note that the referred client_id is the Application ID.
Request Examples
URL Encode Form

The API exposes a token generation endpoint expects your client_id and client_secret to be formatted as application/x-www-form-urlencoded cont
ent type.
curl --location --request POST 'https://partners-staging.api.com/v1/auth

/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'scope=ping' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=[APPLICATION_ID]' \
--data-urlencode 'client_secret=[CLIENT_SECRET]'
HTTP Basic Auth

Alternatively, the API also accepts a Basic Authorization header with the Base64 encoding of the client_id (Application ID) and client
_secret joined by a single colon :.
BASE64_ENCODED_CREDENTIALS = base64_encode(client_id + ":" +
client_secret)
/token' \
--header 'Authorization: Basic [BASE64_ENCODED_CREDENTIALS]' \
--data-urlencode 'grant_type=client_credentials'
Webhook
The API platform is able to send notifications to your system via HTTP POST requests signed with an HMAC digest defined in the Webhook
AUTH section. Please work with your Account Representative to setup your Application's Webhook configurations.
Example Base-URL = https://yourserver.com/webhook
Notification Schema
Name Type Description
eventId string Unique id of the event.
eventTime string The time the event occurred.
eventType string The type of event (e.g. create_order).
metadata.payload object The event object which will be detailed in each Webhook description.
metadata.storeId string Id of the store for which the event is being published.
metadata.applicationId string Id of the application for which the event is being published.
metadata.resourceId string The external identifier of the resource that this event refers to.
metadata.resourceHref string The endpoint to fetch the details of the resource.
Notification Request Example

curl --location --request POST 'https://yourserver.com/webhook' \
--header 'User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_5)
AppleWebKit/537.36 (KHTML, like Gecko) Chrome/75.0.3770.142 Safari/537.
36' \
--header 'Authorization: MAC <hash signature>' \
--header 'Content-Type: application/json' \
--data-raw '{
"eventId": "123456",
"eventTime": "2020-10-10T20:06:02:123Z",
"eventType": "orders.new_order",
"metadata": {
"storeId": "755fd19a-7562-487a-b615-171a9f89d669",
"applicationId": "e22f94b3-967c-4e26-bf39-9e364066b68b",
"resourceHref": "https://partners-staging.api.com/v1/orders
/bf9f1d81-f213-496e-a026-91b6af44996c",
"resourceId": "bf9f1d81-f213-496e-a026-91b6af44996c",
"payload": {}
}
}
Expected Response
The partner application should return an HTTP 200 response code with an empty response body to acknowledge receipt of the webhook event.
Webhook Auth
Webhooks use a standard HMAC signature for your system to validate that the inbound request is coming from our API.
The sent in the Authorization header should be used to validate that the payload was sent by us. The shared client_secret (configured
during onboarding) is used to generate the digest:
Python:
// request_body = Body of the request.

// client_secret = The shared secret key.
hash_signature = getHashSignatureFromAuthHeader() // hash_signature
will be prefixed with "MAC "
hash_signature_digest = hash_signature.split(" ")[1]; // strip off the
prefix "MAC "
hash_signature_digest_decoded = Base64.decode(hash_signature_digest,
UTF_8)
digester = hmac.new(client_secret, request_body, "HmacSHA1");
assert hash_signature_digest_decoded == digester.hexDigest()
Java:
// request_body = Body of the request.
// clientSecret = The shared secret key.
String hashSignature = getHashSignatureFromAuthHeader(); //
hash_signature will be prefixed with "MAC "
String hashSignatureDigest = hashSignature.split(" ")[1]; // strip off
prefix "MAC "
byte[] hashSignatureDigestDecoded = Base64.getDecoder().decode
(hashSignatureDigest);
Mac mac = Mac.getInstance(HMAC_SHA_1);
mac.init(new SecretKeySpec(clientSecret.getBytes(Charsets.UTF_8),
HMAC_SHA_1));
assertArrayEquals(hashSignatureDigestDecoded, mac.doFinal(request_body.
getBytes()));
API Usage Limits
Usage of the API is limited to 20 requests per second (per Application).
Error Responses
List of standard error responses for the API.
HTTP Status Code 400: The request is malformed.
HTTP Status Code 401: Invalid authorization.
HTTP Status Code 403: Authorization not valid for the requested resource.
HTTP Status Code 404: Resource not found.
HTTP Status Code 422: The request body is not valid.
Response body schema: application/json
Specification
Field Type Description
message string The error description.
details string[] List of error details.
Example
{
"message": "Account could not be found: {ext_store_id=,
partner_id=1}",
"details": []
}
Authentication
Scopes
Generate Token
Usage
The Authentication/Authorization API support OAuth2.0 protocol. Only Generate Token operation is supported.
Scopes
The following scopes are available. Scopes must be configured by our internal team to be enabled for an app. Each endpoint requires a given
scope that can be verified on each endpoint documentation. When generating an OAuth2.0 token multiple scopes can be requested.
Scope Description
menus.publish Token has permission to notify the result of a publish menus operation for a
given store.
menus.get_current Token has permission to send the current state of a menu, after being
requested by a webhook event.
menus.pos_publish Token has permission to read available integration targets and to publish
complete menus for selected integration targets.
menus.async_job.read Token has permission to read the status of a menu upser job.
menus.entity_suspension Token has permission to notify the result of a menu entity availability update,
after being requested by a webhook event.
menus.read Token has permission to read the current menus for a given store.
menus.upsert Token has permission to create/update menus for a given store.
orders.customer_payment_update Token has permission to update customer’s payment information for a

previously created order for a given store.
orders.delivery_info_update Token has permission to update delivery information for a previously created
order.
orders.status_update Token has permission to update the order status for a previously created order.
orders.create Token has permission to create new order for a given store.
orders.upsert Token has permission to create and / or update new order(s) for a given store.
ping Token has permission to ping the system.
reports.generate_report Token has permission to request reports for a given store and period of time.
storefront.store_pause_unpause Token has permission to notify the result of a pause/unpause operation, after
being requested by a webhook event.
storefront.store_availability Token has permission to send the current state of store.
storefront.store_hours_configuration Token has permission to send the current store hours configuration.
delivery.provider Token has permission to send the delivery operation result.
callback.error.write Token has permission to send failed webhook event results.
Generate Token
POST /v1/auth/token
Used to generate an OAuth2.0 token that must be used to call all available endpoints.
Client credentials in the request-body and HTTP Basic Auth are supported.
Request
Request body schema: application/x-www-form-urlencoded
Specification
client_id string <uuid> The ID of the client (also known as the Application ID).
client_secret string The secret of the client.
grant_type string The OAuth2.0 grant types supported. Must be client_credentials.
scope string The scope to request, multiple scopes are passed delimited by a space character.
Example

/token' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=[APPLICATION_ID]' \
--data-urlencode 'client_secret=[CLIENT_SECRET]'
Response
Specification
access_token string The OAuth2.0 generated scope.
expires_in integer Time for token expiration, in seconds.
scope string Scopes available for the generated token
token_type string The token type, values is always bearer.
Example
{
"access_token": "oMahtBwBbnZeh4Q66mSuLFmk2V0_CLCKVt0aYcNJlcg.
yditzjwCP7yp0PgR6AzQR3wQ1rTdCjkcPeAMuyfK-NU",
"expires_in": 2627999,
"scope": "ping orders.create",
"token_type": "bearer"
}
Error Responses
HTTP Status Code 400: The request is malformed.
HTTP Status Code 401: Invalid Authorization.
HTTP Status Code 422: The request body is not valid.
Error response body:

message string The error description.
details string[] List of error details.
Example:
{
"message": "Client Secret and Authorization header are null.",
"details": []
}
Usage
The token provided in field access_token is used to authenticate when consuming the API endpoints. Send the token value in the Authorizat
ionheader of every request. The token expiration time is represented in the field expired_in, in seconds. Currently, all tokens are valid for 30
days and should be stored and re-used while still valid.
Example usage:
curl --location --request GET 'https://partners-staging.cloudkitchens.

com/v1/ping' \
--header 'Authorization: Bearer <access_token>' \
--header 'X-Application-Id: <applicationId>' \
--header 'X-Store-Id: <storeId>'
Orders Integrations
Overview
Operations
Integration Flows
Order Lifecycle
Order Creation Flow
Order Cancellation Event Flow
Overview
This section aims to guide the development of order integration, covering order creation flow and state transitions.
Operations
Currently, orders integration supports the following operations
Create order: Creates a new order for a given store. This operation is performed by sending a POST request to /v1/orders.
Update order status: Updates the order state for a previously created order. Supported states are: PREPARED, CANCELED,
FULFILLED. This operation is performed by sending a POST request to /v1/orders/{orderId}/status.
Update order delivery information: Updates delivery information for a previously created order, like destination address, courier,
vehicle, current location, and customer notes. This operation is performed by sending a PUT request to /v1/orders/{orderId}
/delivery.
Event - Intent to cancel order: Partners API sends a webhook event to a pre-configured URL, notifying that a restaurant operator
wants to cancel and order. If the cancel operation succeeds, the order status should be changed to CANCELED by using the endpoint /v1
/orders/{orderId}/status.
Event - Order status update: Partners API sends a webhook event to a pre-configured URL, notifying about an order status transition.
The webhook payload contains the full history of order statuses, with timestamps. Statuses that trigger this event: ORDER_ACCEPTED,
ORDER_READY_TO_PICKUP, ORDER_FULFILLED, ORDER_CANCELED.
Integration Flows
Order Lifecycle
The order lifecycle is composed of the possible state transitions that can happen to the order.
1. The order lifecycle starts with NEW_ORDER status. In general, orders will be created in this status. However, it is possible to create orders
in a more advanced status in case of state transitions happening earlier on the integration side.
2. After a new order is placed it must be accepted, either manually or automatically. This moves the order into the ORDER_ACCEPTED
status.
3. Once the store completes preparation of the order, it moves into the ORDER_READY_TO_PICKUP status.
4. After the order is delivered or picked up by the customer, the state will change to ORDER_FULFILLED.
5. This is the terminal state for a successful order.
An order can be canceled at any point, which will change the status to ORDER_CANCELED. This is the terminal state for a failed order.
Order Creation Flow
Integration flow for the process of creating a new order and state transitions until the order is fulfilled.
1. Partner application creates a new order using POST /v1/orders.
2. When the user accepts the order (can be automatically accepted) Partners API sends an order status update webhook event containing
status ORDER_ACCEPTED.
3. Partner application updates the order status to PREPARED using POST /v1/orders/{orderId}/status.
4. Partner application updates the order status to FULFILLED using POST /v1/orders/{orderId}/status.
Optional: an order status update webhook event may be triggered when the user marks the order as ready to pick up, on the Online Delivery
Provider side, the order status should be changed to the equivalent PREPARED state. The PREPARED status can still be sent through POST /v1
/orders{orderId}/status.
Order Cancellation Event Flow

After an order is created, it can be canceled at any point before it is fulfilled. This integration flow describes the possible scenarios of order
cancelation, 2A represents an order canceled by external action, and 2B represents an order canceled by a restaurant operator.
1 - Partner application creates a new order using POST /v1/orders.
2A - At any point of the order lifecycle, the partner application can update the order status to CANCELED using POST /v1/orders/{orderId}
/status.
2B.1 - When a user requests to cancel an order, an “intent to cancel order” webhook event is sent. When required, the partner application must
try to cancel the order on the Online Delivery Provider side to effectively cancel the order.
2B.2 - If the user request to cancel an order is fulfilled, then the Partner application must update the order status to CANCELED using POST /v1
/orders/{orderId}/status.
Orders Endpoints
Create Order
Update Order
Update Order Status
Models
Create Order
POST /v1/orders
Creates an order for a given store.
Authorization
OAuth2.0 - scope: orders.create
Request
Headers
Header Description
X-Store-Id The ID of the store in your system this call acts on behalf of.
Request Body
Request body schema: application/json
Specification
Field Type Required Description
externalIdentifiers OrderExternalIdentifiers Required The external identifiers of the order.
items Item[] Required Items ordered.
orderedAt string (ISO 8601 Date and Time) Optional The date (in UTC) when the order was placed by the customer
(YYYY-MM-DDThh:mm:ssZ).
currencyCode string Required The 3-letter currency code (ISO 4217) to use for all monetary
values in this order.
customer Person Optional Details about the customer who placed the order.
customerNote string Optional An order-level note provided by the customer.
status string <enum: OrderStatus> Required The current status of the order.
deliveryInfo DeliveryInfo Optional Information about how the order will be delivered, if it is a
delivery type.
orderTotal OrderTotal Required Details about values of the order.
customerPayments CustomerPayment[] Optional Details about the payments made by the customer.
fulfillmentInfo FulfillmentInfo Optional Information on order fulfillment.
Example
{
"externalIdentifiers": {
"id": "69f60a06-c335-46d9-b5a1-97f1a211c514",
"friendlyId": "ABCDE",
"source": "ubereats"
},
"items": [
{
"id": "33e0418f-3d56-4360-ba03-18fc5f8844a3",
"name": "Juicy Cheeseburger",
"quantity": 1,
"note": "Please cook to well done!",
"categoryId": "303de078-870d-4349-928b-946869d4d69b",
"categoryName": "Burgers",
"price": 5.9,
"modifiers": [
{
"id": "d7a21692-9195-43aa-a58f-5395bba8a804",
"name": "Avocado",
"quantity": 1,
"price": 1,
"groupName": "Add ons",
"groupId": "fb52b138-7ac4-42c1-bfd8-664d57113a41",
"modifiers": [
{}
]
}
]
}
],
"orderedAt": "2020-12-20T02:30:00Z",
"currencyCode": "EUR",
"customer": {
"name": "Jane Doe",
"phone": "+1-555-555-5555",
"email": "email@email.com",
"personalIdentifiers": {
"taxIdentificationNumber": "01234567890"
}
},
"customerNote": "Please include extra napkins!",
"status": "NEW_ORDER",
"deliveryInfo": {
"courier": {
"name": "Jane Doe",
"phone": "+1-555-555-5555",
}
},
"destination": {
"postalCode": "20500",
"city": "Washington",
"state": "DC",
"countryCode": "US",
"addressLines": "1600 Pennsylvania Avenue NW",
"location": {
"latitude": 38.8977,
"longitude": 77.0365
}
},
"licensePlate": "ABC 123",
"makeModel": "Honda CR-V",
"lastKnownLocation": {
},
"note": "Gate code 123"
},
"orderTotal": {
"subtotal": 11.97,
"claimedSubtotal": 12.98,
"discount": 1,
"tax": 1.1,
"tip": 2,
"deliveryFee": 5,
"total": 19.07,
"couponCode": "VWXYZ98765"
},
"customerPayments": [
{
"value": 2,
"processingStatus": "COLLECTABLE",
"paymentMethod": "CASH"
}
],
"fulfillmentInfo": {
"pickupTime": "2020-12-20T02:30:00Z",
"deliveryTime": "2020-12-20T02:30:00Z",
"fulfillmentMode": "DELIVERY",
"schedulingType": "ASAP",
"courierStatus": "COURIER_ASSIGNED"
}
}
Response
HTTP Status Code: 200 OK

Response Body
Specification
externalIdentifiers OrderExternalIdentifiers Required The identifiers of the order.
storeId string Required The identifier of the store.
Example
{
"id": "2eb26483-43f5-44ad-ace2-de6a3f1f71a8",
"source": null
},
"storeId": "123456"
}
Update Order
POST /v1/orders/{orderId}
Creates or updates an order for a given store.
Authorization
OAuth2.0 - scope: orders.orders_update
Request
Headers
Header Description
Request Body
Specification
externalIdentifiers OrderExternalIdentifiers Required The external identifiers of the order.
items Item[] Required Items ordered.
orderedAt string (ISO 8601 Date and Time) Optional The date (in UTC) when the order was placed by the customer
(YYYY-MM-DDThh:mm:ssZ).
currencyCode string Required The 3-letter currency code (ISO 4217) to use for all monetary
values in this order.
customer Person Optional Details about the customer who placed the order.
customerNote string Optional An order-level note provided by the customer.
status string <enum: OrderStatus> Required The current status of the order.
deliveryInfo DeliveryInfo Optional Information about how the order will be delivered, if it is a
delivery type.
orderTotal OrderTotal Required Details about values of the order.
customerPayments CustomerPayment[] Optional Details about the payments made by the customer.
fulfillmentInfo FulfillmentInfo Optional Information on order fulfillment.
Example
{
"id": "69f60a06-c335-46d9-b5a1-97f1a211c514",
"source": "ubereats"
},
"items": [
{
"id": "33e0418f-3d56-4360-ba03-18fc5f8844a3",
"name": "Juicy Cheeseburger",
"quantity": 1,
"note": "Please cook to well done!",
"categoryId": "303de078-870d-4349-928b-946869d4d69b",
"categoryName": "Burgers",
"price": 5.9,
"modifiers": [
{
"id": "d7a21692-9195-43aa-a58f-5395bba8a804",
"name": "Avocado",
"quantity": 1,
"price": 1,
"groupName": "Add ons",
"groupId": "fb52b138-7ac4-42c1-bfd8-664d57113a41",
"modifiers": [
{}
]
}
]
}
],
"orderedAt": "2020-12-20T02:30:00Z",
"customer": {
"name": "Jane Doe",
"phone": "+1-555-555-5555",
}
},
"customerNote": "Please include extra napkins!",
"status": "NEW_ORDER",
"deliveryInfo": {
"courier": {
"name": "Jane Doe",
"phone": "+1-555-555-5555",
}
},
"destination": {
"state": "DC",
"addressLines": "1600 Pennsylvania Avenue NW",
"location": {
}
},
},
},
"orderTotal": {
"subtotal": 11.97,
"claimedSubtotal": 12.98,
"discount": 1,
"tax": 1.1,
"tip": 2,
"deliveryFee": 5,
"total": 19.07,
"couponCode": "VWXYZ98765"
},
{
"value": 2,
}
],
"fulfillmentInfo": {
"pickupTime": "2020-12-20T02:30:00Z",
"deliveryTime": "2020-12-20T02:30:00Z",
"fulfillmentMode": "DELIVERY",
"schedulingType": "ASAP",
"courierStatus": "COURIER_ASSIGNED"
}
}
Response
Response Body
Specification
externalIdentifiers OrderExternalIdentifiers Required The identifiers of the order.
storeId string Required The identifier of the store.
Example
{
"id": "2eb26483-43f5-44ad-ace2-de6a3f1f71a8",
"source": null
},
"storeId": "123456"
}
Update Order Status
POST /v1/orders/{orderId}/status
Update order status.
Authorization
OAuth2.0 - scope: orders.status_update
Request
Headers
Header Description
Request Body
Specification
orderStatus string <enum: OrderStatus> Required The requested status to transition the order to, only PREPARED,
CONFIRMED, CANCELED and FULFILLED are accepted.
Example
{
"orderStatus": "PREPARED"
}
Response
HTTP Status Code: 202 Accepted
POST /v1/{orderId}/payments
Update payment information for a given order.
Authorization
OAuth2.0 - scope: orders.orders_update
Request
Headers
Header Description
Request Body
Specification
currencyCode string Required The 3-letter currency code (ISO 4217) to use for all
monetary values in this order.
customerPayments CustomerPayment[] Required Details about the payments made by the customer.
Example
{
{
"value": 2,
}
]
}
Response
Update order delivery information.
Authorization
OAuth2.0 - scope: orders.delivery_info_update
Request
Headers
Header Description
Request Body
Specification
deliveryInfo DeliveryInfo Required The requested status to transition the order to.
Example
{
"deliveryInfo": {
"courier": {
"name": "Jane Doe",
"phone": "+1-555-555-5555",
}
},
"destination": {
"state": "DC",
"addressLines": [
"ullamco et",
"velit non Lorem deserunt id"
],
"location": {
}
},
},
}
}
Response
Models
OrderExternalIdentifiers
The external identifiers of the order.
id string Required Unique ID for the order that was placed.
friendlyId string Required ID used for driver pickup and restaurant management.
source string Optional Describes the source of the order, typically from a food ordering marketplace.
Item
An order item.
id string Optional The unique ID of the item.
name string Optional The name of the item as displayed to the customer.
quantity integer Required The quantity of the item ordered by the customer.
note string Optional An optional item-level note provided by the customer.
categoryId string Optional The unique ID of the category of this item.
categoryName string Optional The name of the category of this item.
price decimal Optional The price of the sold item.
skuPrice decimal Optional The stored sku price of this item.
modifiers ItemModifier[] Optional Modifiers to the base item.
ItemModifier
An order item modifier.
id string Optional The unique ID of the modifier product.
name string Optional The name of the modifier as displayed to the customer.
quantity integer Required The number of times the modifier was applied to the given item.
price decimal Optional The price of the sold modifier.
skuPrice decimal Optional The stored sku price of this item.
groupName string Optional The parent group of the modifier item.
groupId string Optional The unique ID of the parent group.
modifiers ItemModifier[] Optional Nested modifiers applied to the item.
Person
Details about a person.
name string Required The person's name as it should be displayed.
phone string Optional The person's phone number.
email string Optional The person's email address.
personalIdentifiers PersonalIdentifiers Optional The person's personal identifiers (e.g. tax identification number).
PersonalIdentifiers
The person's personal identifiers (e.g. tax identification number).
taxIdentificationNumber string Optional Person tax identification number.
OrderStatus - enum
The status of the order.
Value Description
NEW_ORDER The order was placed by the customer.
CONFIRMED The order was accepted by the restaurant.
PICKED_UP The order was picked up by the customer or the courier.
CANCELED The order was canceled.
FULFILLED The order was delivered to the customer.
PREPARED The order was prepared and is ready to be picked up.
UNKNOWN The current status is unknown.
DeliveryInfo
Information on order's delivery process.
courier Person Optional Details about the delivery courier.
destination Address Optional The customer's address.
licensePlate string Optional License plate of a vehicle used by the courier.
makeModel string Optional Make and model of a vehicle used by the courier.
lastKnownLocation Location Optional Last known location of the courier.
note string Optional Special delivery instructions, if any.
Address
A delivery address.
postalCode string Optional Postal code of the address.
city string Optional The city/town portion of the address.
state string Optional Highest administrative subdivision which is used for postal addresses of a country or
region. For example, this can be a state, a province, or a prefecture.
countryCode string Optional CLDR country code. See http://cldr.unicode.org/
addressLines string[] Optional Address lines (e.g. street, PO Box, or company name).
location Location Optional Latitude and longitude of the address.
Location
Latitude and longitude.
latitude decimal Required The latitude of the location.
longitude decimal Required The longitude of the location.
OrderTotal
Details about values of the order.
subtotal decimal Required The order's subtotal, as the sum of all item and modifier prices.
claimedSubtotal decimal Optional Claimed subtotal for the order. This figure does not have to match the sum of all item and
modifier prices. If claimedSubtotal is set, its value takes precedence over the value in sub
total field.
discount decimal Optional Any discount amount for the order.
tax decimal Optional Tax paid by the customer.
tip decimal Optional Tip paid by the customer.
deliveryFee decimal Optional Delivery fee.
total decimal Optional Order total including everything paid by the customer.
couponCode string Optional Coupon code applied to the order.
CustomerPayment
Describes a customer payment for a given order.
value decimal Required The portion of the overall amount that needs to be paid.
processingStatus string <enum: PaymentProcessingStatus> Required The processing status of the payment.
paymentMethod string <enum: PaymentMethod> Required The payment method.
PaymentProcessingStatus - enum
The processing status of the payment.
Value Description
COLLECTABLE It means that payment will be collected at delivery time.
PROCESSED It means that the payment has already been processed.
PaymentMethod - enum
The method of payment.
Value Description
CASH Cash payment method.
CARD Card payment method.
CHEQUE Cheque (Checke) payment method.
OTHER Other forms of payment.
UNKNOWN Unknown form of payment.
FulfillmentInfo
Information on order fulfillment.
pickupTime string (ISO 8601 Date and time) Optional Estimated time (in UTC) that the courier or customer will pick
up the order.
deliveryTime string (ISO 8601 Date and time) Optional Estimated time (in UTC) when the order is expected to be
delivered. This should be filled in if FulfillmentMode is delivery.
fulfillmentMode string <enum: FulfillmentMode> Optional How an order is expected to be fulfilled.
schedulingType string <enum: SchedulingType> Optional Describes whether this order should be cooked as soon as
possible, or some time in the future. Please use the
pickupTime and/or deliveryTime to indicate when. If no
scheduling type is provided, we assume the order should be
prepared as soon as possible.
courierStatus string <enum: CourierStatus> Optional The current status of the courier.
FulfillmentMode - enum
How an order is expected to be fulfilled.
Value Description
DELIVERY The order is meant to be delivered by a courier.
RESTAURANT_DELIVERY The restaurant is responsible for managing the delivery of this order.
PICKUP The order is meant to be picked up by the customer.
SchedulingType - enum
Describes whether this order should be cooked as soon as possible, or sometime in the future.
Value Description
ASAP
FIXED_TIME
CourierStatus - enum
The status of the courier.
Value Description
COURIER_ASSIGNED The courier was assigned to the order.
COURIER_ON_ROUTE_TO_PICKUP The courier is on its way to pick up the order.
COURIER_ARRIVED The courier arrived to pick up the order.
COURIER_PICKED_UP_FOOD The courier is on its way to deliver the order to the customer.
COURIER_COMPLETED The order was delivered.
Menus Integration
Overview
Operations
Integration Flows
Menu publish flow
Update menu entities availability flow
Upsert hours flow
Failed Event Flow
Overview
This section aims to guide the development of menu integration, covering the process to integrate with events to publish and sync menus and
related data for menu consumers.
Operations
Currently, menu integration supports the following operations:
Menu publish: Partners API sends a webhook event containing menus that a user wants to push to an integrated service. The partner
application must perform the menu publish operation and then send the event result to the callback endpoint.
Upsert hours: Partners API sends a webhook event containing a configuration of menu hours that a user wants to push to an integrated
service. The partner application must perform the upsert hours operation and then send the event result to the callback endpoint.
Update menu entities availability: Partners API sends a webhook event requesting to suspend/unsuspend a particular item on an
integrated service. The partner application must perform the update availability operation and then send the event result to the callback
endpoint.
Send menu: Partners API sends a webhook event requesting the partner application to send the currently available menus in an
integrated service. The partner application must fetch the current menus and then send them using the callback endpoint.
Callback error: Endpoint to send the id of a webhook event when a requested operation could not be performed by the partner
application, the request body must contain the cause of the failure.
Integration Flows
Menu publish flow
This flow describes the process of publishing a menu to an integrated service and syncing the current menus with our API.
1. Partners API sends the “send menu” webhook event, requesting the partner application to send the currently available menus for a given
store in an integrated service.
2. The partner application sends the webhook event result containing the current menus for the store. Partners API will take the current
menus and attempt to intelligently match our menu entities to what already exists in the partner menu.
3. Partners API sends a menu publish webhook event containing the matched and new menu entities. Matched entities will have the ids
that were sent in the previous step or in previous menu syncs. New menu entities will have random UUIDs and those entities that should
be deleted will be omitted from the webhook payload.
4. The partner application must perform the menu publish operation for the given store in an integrated service and then send the event
result containing the ids for newly created menu entities.
Update menu entities availability flow
This flow describes the process of suspending/unsuspending a given menu entity on an integrated service.
1. Partners API sends an “update menu entity availability“ webhook event, requesting to suspend/unsuspend a menu entity.
2. Partner application performs the request operation within the integrated service and then sends the webhook event result to POST /v1
/menus/entity/availability/bulk.
Upsert hours flow
This flow describes the process of creating/updating only the menu hours for a given store on an integrated service.
1. Partners API sends an “upsert hours“ webhook event request to modify menu hours for a given store on an integrated service.
2. Partner application performs the request operation within the integrated service and then sends the webhook event result to POST /v1
/menus/hours.
Failed Event Flow
This flow describes the process to inform that an operation requested by a webhook event could not be performed successfully by the partner
application. The event id must be used to call POST /v1/callback/error.
1. Partners API sends any webhook event requesting to perform an operation within an integrated service (menu publish, upsert hours,
update menu entities availability, send menu).
2. Partner application fails to perform the requested operation within the integrated service.
3. Partner application informs the failure and the cause using POST /v1/callback/error.
Menu Events And Callbacks

Menu Publish
Send Menu
Upsert Hours
Callback Errors
Models
Menu Publish
event type: menus.menu_publish
Event representing menu update - requiring partner action to update 3PD system.
Webhook Event
Request
Headers
Authorization string (MAC <hash signature>) HMAC signature to validate the request origin.
Request Body
Specification
eventId string Required Unique id of the event.
eventTime string Required The time the event occurred.
eventType string Required The type of event: menus.menu_publish
metadata.storeId string Required Id of the store for which the event is being published.
metadata.applicationId string Required Id of the application for which the event is being published.
metadata.payload UpsertFullMenuEvent Required Event data containing the upserted MenuData.
Example
{
"eventId": "5d779a68-c06f-4f94-a8e9-79c59ddd94e5",
"eventTime": "2021-05-20T18:57:12Z",
"eventType": "menus.menu_publish",
"metadata": {
"storeId": "25346",
"applicationId": "a8a33dc8-9842-4fc2-9c1a-532e3c92781a",
"payload": {
"menuData": {
"menus": {
"name": "Tasty BBQ",
"categoryIds": [
"string"
],
"fulfillmentModes": [
"DELIVERY"
],
"id": "da0e4e94-5670-4175-897a-3b7dde45bed5",
"hoursData": {
"timeZone": "UTC, America/Los_Angeles",
"regularHours": [
{
"days": [
"MONDAY"
],
"timeRanges": [
{
"start": {
"hour": 0,
"minute": 0,
"second": 0,
"nano": 0
},
"end": {
"hour": 0,
"minute": 0,
"second": 0,
"nano": 0
}
}
]
}
],
"specialHours": [
{
"date": "2019-08-24",
"timeRanges": [
{
"start": {
"hour": 0,
"minute": 0,
"second": 0,
"nano": 0
},
"end": {
"hour": 0,
"minute": 0,
"second": 0,
"nano": 0
}
}
],
"type": "OPEN"
}
]
}
},
"categories": [
{
"empty": true,
"property1": {
"name": "Breakfast",
"description": "All early morning items
served up hot and fresh!",
"itemIds": [
"string"
],
"id": "da0e4e94-5670-4175-897a-3b7dde45bed5"
},
"property2": {
"description": "All early morning items
served up hot and fresh!",
"itemIds": [
"string"
],
"id": "da0e4e94-5670-4175-897a-3b7dde45bed5"
}
}
],
"items": {
"name": "Bagel",
"description": "Delicious bagel!",
"modifierGroupIds": [
"string"
],
"status": {
"saleStatus": "TEMPORARILY_NOT_FOR_SALE",
"suspendedUntil": "2019-08-24T14:15:22Z"
},
"price": 25.21,
"id": "da0e4e94-5670-4175-897a-3b7dde45bed5",
"photoIds": [
"string"
],
"priceOverrides": "$1.5 as a customer item, $1 as a
modifier."
},
"modifierGroups": {
"name": "Choose your type of bagel",
"minimumSelections": 0,
"maximumSelections": 0,
"maxPerModifierSelectionQuantity": 0,
"itemIds": [
"string"
],
"id": "da0e4e94-5670-4175-897a-3b7dde45bed5"
},
"photos": {
"url": "https://www.google.com/images/branding
/googlelogo/2x/googlelogo_color_272x92dp.png",
"fileName": "this image.jpg",
"id": "e9174f75-a293-4908-bba7-9db69871ad81",
"contentType": "image/jpeg, image/png"
}
}
}
}
}
Expected Response
Empty response body.
Callback Endpoint
POST /v1/menus/publish
Request
Headers
Field Description
X-Event-Id Unique identifier of the event that this callback refers to.
Request Body
Specification
requestedToCreatedEntityIds map<string, string> Required A map for entities created by the Upsert containing the
IDs of the requested entities mapped to the IDs of
entities created by the request. Our system will use the
IDs returned in this map to send updates to these
entities in future requests.
Example
{
"requestedToCreatedEntityIds": {
"empty": true,
"property1": "string",
"property2": "string"
}
}
Response
HTTP Status Code: 204 No content
event type: menus.update_menu_entities_availabilities
Event representing menu items availability change - requiring partner action to update 3PD system.
Webhook Event
Request
Headers
Request Body
Specification
eventType string Required The type of event: menus.

update_menu_entities_availabilities
metadata.applicationId string Required Id of the application for which the event is being
published.
metadata.payload BulkUpdateItemStatusEvent Required Event data containing list of item status updates.
Example
{
"eventTime": "2021-05-20T18:57:12Z",
"eventType": "menus.update_menu_entities_availabilities",
"metadata": {
"storeId": "25346",
"payload": {
"updates": [
{
"selector": {
"id": "string",
"isModifier": true
},
"status": {
}
}
]
}
}
}
Expected Response

Callback Endpoint
POST /v1/menus/entity/availability/bulk
Request
Headers
Field Description
Response
Send Menu
event type: menus.send_menu
Event requesting the partner to send back the current menu in the 3PD system.
Webhook Event
Request
Headers
Request Body
Specification
eventType string Required The type of event: menus.send_menu
Example
{
"eventTime": "2021-05-20T18:57:12Z",
"eventType": "menus.send_menu",
"metadata": {
"storeId": "25346",
}
}
Expected Response
Callback Endpoint
POST /v1/menus/current
Request
Headers
Field Description
Request Body
Specification
menuData MenuData Required Representation of a third party menu system.
Example
{
"menuData": {
"menus": {
"name": "Tasty BBQ",
"categoryIds": [
"string"
],
"fulfillmentModes": [
"DELIVERY"
],
"id": "da0e4e94-5670-4175-897a-3b7dde45bed5",
"hoursData": {
"timeZone": "UTC, America/Los_Angeles",
"regularHours": [
{
"days": [
"MONDAY"
],
"timeRanges": [
{
"start": {},
"end": {}
}
]
}
],
"specialHours": [
{
"date": "2019-08-24",
"timeRanges": [
{
"start": {},
"end": {}
}
],
"type": "OPEN"
}
]
}
},
"categories": [
{
"empty": true,
"property1": {
"description": "All early morning items served up
hot and fresh!",
"itemIds": [
"string"
],
"id": "da0e4e94-5670-4175-897a-3b7dde45bed5"
},
"property2": {
"description": "All early morning items served up
hot and fresh!",
"itemIds": [
"string"
],
"id": "da0e4e94-5670-4175-897a-3b7dde45bed5"
}
}
],
"items": {
"name": "Bagel",
"description": "Delicious bagel!",
"modifierGroupIds": [
"string"
],
"status": {
},
"price": 25.21,
"id": "da0e4e94-5670-4175-897a-3b7dde45bed5",
"photoIds": [
"string"
],
"priceOverrides": "$1.5 as a customer item, $1 as a
modifier."
},
"modifierGroups": {
"name": "Choose your type of bagel",
"minimumSelections": 0,
"maximumSelections": 0,
"maxPerModifierSelectionQuantity": 0,
"itemIds": [
"string"
],
"id": "da0e4e94-5670-4175-897a-3b7dde45bed5"
},
"photos": {
"url": "https://www.google.com/images/branding/googlelogo/2x
/googlelogo_color_272x92dp.png",
"fileName": "this image.jpg",
"id": "e9174f75-a293-4908-bba7-9db69871ad81",
"contentType": "image/jpeg, image/png"
}
}
}
Response
Upsert Hours
event type: menus.upsert_hours

Event representing menu hours update - requiring partner action to update 3PD system.
Webhook Event
Request
Headers
Request Body
Specification
eventType string Required The type of event: menus.send_menu
metadata.payload UpsertHoursEvent Required Event data containing all Menu Hours.
Example
{
"eventTime": "2021-05-20T18:57:12Z",
"eventType": "menus.upsert_hours",
"metadata": {
"storeId": "25346",
"payload": {
"hoursData": {
"storeTimeZone": "America/Los_Angeles",
"regularHours": [
{
"daysOfWeek": [
"MONDAY",
"TUESDAY"
],
"hours": [
{
"start": {
"hours": 8
},
"end": {
"hours": 12
}
}
]
}
],
"specialHours": [
{
"date": {
"year": 2021,
"month": 4,
"day": 1
},
"hours": [
{
"start": {
"hours": 8
},
"end": {
"hours": 12
}
}
],
"isClosed": true
}
]
}
}
}
}
Expected Response
Callback Endpoint
POST /v1/menus/hours
Request
Headers
Field Description
Response
Callback Errors
POST /v1/callback/error
This endpoint should be used to publish a callback error when the partner application was not able to complete an operation requested by a
webhook event.
Request
Headers
Field Description
Response
Models
UpsertFullMenuEvent
Event data containing the upserted MenuData.
menuData MenuData Required Upserted MenuData.
BulkUpdateItemStatusEvent
Event data containing a list of item status updates.
updates UpdateItemStatusEntry[] Required List of item status updates.
UpsertHoursEvent
Event data containing all Menu Hours.
menuHoursData map<string, HoursData> Required Menu IDs to Hours
UpdateItemStatusEntry
Update the status of an item to the provided value.
selector ItemSelector Required Selector of the item of interest.
status string <enum: ItemStatus> Required Status of the item
ItemSelector
Used to select a specific item.

id string Required Identifier of the item.
isModifier boolean Required True, if the item is used as a modifier only.
MenuData
MenuData contains all menu entities and their relations.
menus map<string, Menu> Required All Menus for the store, indexed by ID
categories map<string, Category> Required All Categories for the store, indexed by ID
items map<string, Item> Required All Items for the store, indexed by ID
modifierGroups map<string, ModifierGroup> Required All ModifierGroups for the Store, indexed by ID
photos map<string, Photo> Required All photos for the store, indexed by ID
Category
Categories contain a list of Item references.
id string Required Identifier for Category.
name string Required Name of Category.
description string Optional Description of Category.
itemIds string[] Optional All items in the category.
Item/MenuItem
Items are sold on the Menu. Modifiers to items are items themselves and their relationship is defined by ModifierGroup.
id string Required Internal identifier of this Item.
name string Required Name of this Item
description string Required Description of this Item
modifierGroupIds string[] Optional Identifiers of each ModifierGroup within this Item.
status string <enum : ItemStatus> Required Status that determines whether an item is for sale or not.
price Money Required Price of the item.
photoIds string[] Required A list of Photo references associated with the Item.
priceOverrides ItemPriceOverride[] Required Specify price overrides for different service slugs.
ItemStatus
Represents whether an Item is for sale, indefinitely not for sale, or not for sale until a specific time.
saleStatus string <enum : SaleStatus> Required Sale status of the Item.
suspendedUntil string (ISO 8601 Date and time) Optional ISO-8601 timestamp representing the time the
saleStatus value is supposed to change to FOR_SALE.
Set only when current saleStatus value is
TEMPORARILY_NOT_FOR_SALE (YYYY-MM-DDThh:
mm:ssZ).
Menu
A menu for a store.
id string Required Internal identifier for Menu.
name string Required Name of the Menu.
hours Hours Optional Menu hours represented as HoursData if they exist.
description string Optional Description of the Menu.
categoryIds string[] Optional Identifiers of the categories within this Menu.
fulfillmentModes MenuFulfillmentMode[] Optional The ways in which this menu may be fulfilled. If no values
are specified, it is assumed that all fulfillment types are
allowed.
ModifierGroup
Items are sold on the menu. Modifiers to items are items themselves and their relationship is defined by ModifierGroup.
id string Required Identifier for ModifierGroup.
name string Required Name of ModifierGroup.
description string Optional Description for this ModifierGroup.
minimumSelections integer Optional Minimum number of selections customers can make in this
ModifierGroup. 0 means no min limits. Default is 0.
maximumSelections integer Optional Maximum number of selections customers can make in this
ModifierGroup. 0 means no max limits. Default is 0.
maxPerModifierSelectionQuantity integer Optional Maximum number of selections customers can make for
each modifier item in this ModifierGroup. 0 means there is
no limit to how many times they can select a single modifier
item. If not specified, a value of 1 will be used as the default
value. Default is 1.
itemIds string[] Optional Identifiers of each Item within this ModifierGroup.
Photo
All data required to represent a Photo for an entity in menus.
id string Required Identifier of Photo.
contentType string Required Content type of the photo.
url string Required URL of the photo.
fileName string Optional File name.
See this guide
Storefront Integration
Overview
Operations
Integration Flows
Get store availability event flow
Pause/Unpause event flow
Overview
This section aims to guide the development of storefront integration with the Partner API. The document will describe the integration flow of
storefront events, endpoints, and prerequisites.
Operations
Currently, storefront integration supports 3 operations:
Update store hours configuration - The partner sends the current store hours configuration through the endpoint /v1/storefront/hours. Sen
ding a store hour configuration is a prerequisite to enable other available operations.
Get store availability - Partners API sends a webhook event requesting the partner to send the current store availability state through the
endpoint /v1/storefront/availability. The default frequency of webhook events is 5 minutes.
Pause/Unpause store - Partners API sends a webhook event requesting the partner to pause/unpause a store, the partner must send
the event result through the endpoint /v1/storefront/{pause | unpause}, this will trigger the “store availability event” flow to confirm the
current store state. Implementing the “get store availability” is a prerequisite for the pause/unpause event integration.
In addition to these 3 events, the partner can consume the endpoint /v1/storefront/availability to proactively send any updates on the availability
for a given store.
Integration Flows
Get store availability event flow
To keep the store state in sync, Partners API sends a “get store availability“ webhook event, the default frequency is 5 minutes. The Partner
application must send the current store state for a given store, preferably by consulting the current status of the store.
1. Partners API sends a “get store availability” webhook event every 5 minutes.
2. The Partner application must send the current store state using POST /v1/storefront/availability
Pause/Unpause event flow
When a user requests to pause/unpause a store Partners API sends a webhook event, the Partner application must perform the requested
operation (pause or unpause the store) and then send the result to /v1/storefront/{pause|unpause}. Finishing this workflow will trigger a “Get store
availability event flow”.
1. Partners API sends a webhook event requesting to pause unpause a store
2. Partner application must perform the required operation (pause or unpause) and then send the result to POST /v1/storefront/
{pause|unpause}.
3. Partners API sends a “get store availability”.
4. The Partner application must send the current store state using POST /v1/storefront/availability
Storefront Events And Callbacks

Pause store
Unpause store
Models
event type: storefront.get_store_availability
Event requesting the current store availability state, after performing the operation, the result must be sent to the callback endpoint.
Webhook Event
Request
Headers
Request Body
Specification
eventType string Required The type of event: storefront.get_store_availability
Example
{
"eventTime": "2021-05-20T18:57:12Z",
"eventType": "storefront.get_store_availability",
"metadata": {
"storeId": "25346",
}
}
Expected Response
Callback Endpoint
POST /v1/storefront/availability
Request
Headers
Field Description
Request Body
Specification
storeState string <enum: StoreState> Required, if The current store state.

eventResultMetadata is
SUCCEEDED
statusChangedAt string (ISO 8601 Date and Time) Required, if The time when the store hours configuration
eventResultMetadata is changed(YYYY-MM-DDThh:mm:ssZ).
SUCCEEDED
eventResultMetadata EventResultMetadata Required Information about the result of the event.
Example
{
"storeState": "OPEN",
"statusChangedAt": "2021-07-20T22:24:48Z",
"eventResultMetadata": {
"operationStatus": "SUCCEEDED",
"additionalInformation": "details",
"operationFinishedAt": "2021-07-20T22:24:48Z"
}
}
Response
Pause store
event type: storefront.pause_store
Event requesting to pause a given store, after performing the operation, the result must be sent to the callback endpoint.
Webhook Event
Request
Headers
Request Body
Specification
Example
{
"eventTime": "2021-05-20T18:57:12Z",
"eventType": "storefront.pause_store",
"metadata": {
"storeId": "25346",
"applicationId": "a8a33dc8-9842-4fc2-9c1a-532e3c92781a"
}
}
Expected Response
Callback Endpoint
POST /v1/storefront/pause
Request
Headers
Field Description
Request Body
Specification
closureId string Optional Id required to unpause a store, if available
Example
{
}
}
Response
Unpause store
event type: storefront.unpause_store
Event Requesting to unpause a given store, after performing the operation, the result must be sent to the callback endpoint.
Webhook Event
Request
Headers
Request Body
Specification
Example
{
"eventTime": "2021-05-20T18:57:12Z",
"eventType": "storefront.unpause_store",
"metadata": {
"storeId": "25346",
"applicationId": "a8a33dc8-9842-4fc2-9c1a-532e3c92781a"
}
}
Expected Response
Callback Endpoint
POST /v1/storefront/unpause
Request
Headers
Field Description
Request Body
Specification
Example
{
}
}
Response
Models
OperationStatus - enum
Status of the operation requested by an event.
Value Description
SUCCEEDED The operation was successfully performed.
INTERNAL_ERROR An internal error occurred causing the operation to fail.
AUTHENTICATION_FAILURE Could not authenticate with the third party.
AUTHORIZATION_FAILURE Not allowed to perform the requested operation.
UNKNOWN_FAILURE Unknown error when interacting with the third party.
INVALID_STORE_STATE The operation could not be completed due to the internal state of the store.
INVALID_STORE_CONFIGURATION The store has not valid configuration to perform the requested operation.
OPERATION_NOT_SUPPORTED The service does not support the operation.
IGNORED_ALREADY_IN_REQUESTED_STATE The store is already in the requested state.
INVALID_REQUEST The event request was invalid.
EventResultMetadata
Information about the result of a storefront event.
operationStatus string <enum: OperationStatus> Required Status of the operation requested by the event.
additionalInformation string Optional Additional details about the event result, if available.
operationFinishedAt string (ISO 8601 Date and Time) Required Time when the processing of the event finished (YYYY-MM-
DDThh:mm:ssZ).
StoreState - enum
Represents the current state of a store.
Value Description
OPEN Store is open.
OFF_HOUR Store is not supposed to operate at this time.
SERVICE_PROVIDER_PAUSED Store was pause by the third party.
OPERATOR_PAUSED Store was paused by the restaurant operator.
SERVICE_PROVIDER_PAUSED_COURIERS_UNAVAILABLE Store is paused by third party because there are no couriers

available to deliver food.
STORE_UNAVAILABLE Store is not available for customers to order food.
HOLIDAY_HOUR Store is offline because of special hour setting.
MENU_UNAVAILABLE Store is not providing a menu.

SERVICE_PROVIDER_PAUSED_MISCONFIGURED The store is not configured properly.
OPEN_FOR_PICKUP_ONLY The store is open for pickup orders only.
OPEN_FOR_DELIVERY_ONLY The store is open for delivery orders only.
DayOfWeek - enum
Value
MONDAY
TUESDAY
WEDNESDAY
THURSDAY
FRIDAY
SATURDAY
SUNDAY
SpecialHourType - enum
Store state that should be applied during the configured special hour.
Value Description
OPEN The store state will be set to OPEN during the configured special hour.
CLOSED The store state will be set to CLOSED during the configured special hour.
StoreHoursConfiguration
The current store hours configuration.
deliveryHours StoreHours Optional The configured store hours offering delivery.
pickupHours StoreHours Optional The configured store hours offering pickup.
timezone string (from Time Zone Database) Optional The store time zone identifier. (e.g. America/New_York)
StoreHours
Represents store hours configuration with regular hours and special hours.
regularHours RegularHours Required List of regular hours configuration.
specialHours SpecialHours Optional List of special hours configuration.
RegularHours
Describes the configuration of regular store hours.
dayOfWeek string <enum: Required The day of the week this configuration applies.
DayOfWeek>
timeRanges TimeRange Required Hours range applied to the provided day of the week.
SpecialHours
Describes the configuration of special store hours.
date string (ISO 8601 Date) Required Date the special hour configuration applies (yyyy-MM-dd).
timeRanges TimeRange Required Hours range applied to configured date.
specialHourType string <enum: SpecialHourType> Required Store state that should be applied in the configured date and time.
TimeRange
The time range on a given date.
startTime string (ISO 8601 Time) Required Start time of the range in 24 hour format (HH:mm).
endTime string (ISO 8601 Time) Required End time of the range in 24 hour format (HH:mm).

Online Delivery Provider API Documentation

Uploaded by

Document Information

Original Description:

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Online Delivery Provider API Documentation

Uploaded by

Copyright:

Available Formats

Online Delivery Provider Docs

For testing purposes, we offer a staging environment.

Onboard your application

Your Account Representative will send the two credentials to you.

Onboard your webhook configurations

Onboard your store(s)

API General Definitions

curl --request GET 'https://partners-staging.api.com/v1/resource/123' \

X-Application-Id The plain-text Application Id, provided at onboarding.

With these headers, the system will:

Note that the referred client_id is the Application ID.

URL Encode Form

curl --location --request POST 'https://partners-staging.api.com/v1/auth

HTTP Basic Auth

Example Base-URL = https://yourserver.com/webhook

Name Type Description

eventId string Unique id of the event.

eventTime string The time the event occurred.

eventType string The type of event (e.g. create_order).

metadata.resourceHref string The endpoint to fetch the details of the resource.

Notification Request Example

// request_body = Body of the request.

API Usage Limits

Usage of the API is limited to 20 requests per second (per Application).

List of standard error responses for the API.

HTTP Status Code 400: The request is malformed.

HTTP Status Code 401: Invalid authorization.

HTTP Status Code 404: Resource not found.

HTTP Status Code 422: The request body is not valid.

Response body schema: application/json

Field Type Description

message string The error description.

details string[] List of error details.

menus.upsert Token has permission to create/update menus for a given store.

orders.customer_payment_update Token has permission to update customer’s payment information for a

ping Token has permission to ping the system.

storefront.store_availability Token has permission to send the current state of store.

delivery.provider Token has permission to send the delivery operation result.

callback.error.write Token has permission to send failed webhook event results.

Request body schema: application/x-www-form-urlencoded

client_secret string The secret of the client.

grant_type string The OAuth2.0 grant types supported. Must be client_credentials.

curl --location --request POST 'https://partners-staging.api.com/v1/auth

Response body schema: application/json

Field Type Description

access_token string The OAuth2.0 generated scope.

expires_in integer Time for token expiration, in seconds.

scope string Scopes available for the generated token

token_type string The token type, values is always bearer.

HTTP Status Code 401: Invalid Authorization.

HTTP Status Code 422: The request body is not valid.

Error response body:

Field Type Description

details string[] List of error details.

curl --location --request GET 'https://partners-staging.cloudkitchens.

Currently, orders integration supports the following operations

Order Creation Flow

Order Cancellation Event Flow

1 - Partner application creates a new order using POST /v1/orders.

Creates an order for a given store.

OAuth2.0 - scope: orders.create

X-Application-Id The plain-text Application Id, provided at onboarding.