Ownly POS integration
v2

Connect your POS to Ownly.

Push your menu, receive orders and keep order status in sync. The guides explain what each integration does; the API reference gives every contract.

Build the integration in this order.

  1. Authenticate your requests.Authentication
  2. Push your menu and handle the processing callback.Menu push
  3. Expose the order endpoint and receive orders.Order relay
  4. Send accepted, cancelled and food ready; receive customer cancellations.Order status exchange
  5. Expose the rider status endpoint and, if you need to call customers or riders, use call masking.Rider status
  6. Keep stock and store availability current.Inventory update

Follow one order through both systems.

How an order moves between Ownly and your downstream system, from the new order to delivery.

Order delivery flow between the Ownly system and the downstream systemOwnly SystemDownstream SystemPush New OrderProcess New OrderOrderAcceptanceOrder CancelCancellationAcceptedOrder AcknowledgementSend AcknowledgementOrder CancellationProcess Order CancellationProcess Food Ready StatusFood ReadyProcess Rider AssignmentProcess Rider AssignmentProcess Rider DispatchProcess Rider DispatchProcess Rider DeliveredProcess Rider Delivered

These calls cover the whole integration.

Authentication.

Downstream systems authenticate with Basic Auth. Each contract also lists the request header it expects.

Key header

Auth key

key: <your-auth-key>
Send what each contract lists. Inventory update documents the Authorization header; every other call documents the key header. Keep both server-side and never ship them in a client app or a repository.

Which header each call uses

EndpointHeaderCalled by
POST /api/v1/menukeyYour POS
POST /api/v1/item-statusAuthorizationYour POS
POST /api/v1/store-statuskeyYour POS
POST /api/v1/order-statuskeyBoth
GET /api/v1/contactkey, plus Accept: application/jsonYour POS
POST /api/v1/order/keyOwnly
POST <upstream-host>/api/v1/rider-statuskeyOwnly

How the integration works.

The document is a reference for downstream systems integrating with Ownly for menu, order, order status exchange, item inventory and restaurant status.

Menu integration

Populate a restaurant's menu on Ownly by pushing it from your system. There are no partial updates: every push replaces the existing menu with the new version.

Ownly exposes

An endpoint to publish the menu.

Order relay

Every time a customer places an order, Ownly relays the order details to your system.

You expose

An endpoint that receives the order from Ownly.

Order status exchange

Once an order is placed it goes through a life cycle, and both systems exchange its status.

Your system pushes order acceptance, order rejection and food ready to Ownly. Ownly pushes the customer cancellation and the rider updates, from assignment to delivery, to your system.

Ownly exposes

An endpoint to receive acceptance, cancellation and food ready from your system.

You expose

An endpoint to receive the customer cancellation from Ownly.

You also expose

An endpoint for rider status updates.

Item inventory

Update the stock status of an item, add-on or variant. Your system calls Ownly with the stock details.

Ownly exposes

An endpoint for item inventory status updates.

Restaurant status

Switch a store on or off. Use it to take a restaurant offline when the kitchen is closed or overwhelmed.

Ownly exposes

An endpoint to update store availability.

Call masking

Retrieve a masked contact number and an OTP to start a call between two parties on an order, for example from the restaurant to the customer.

Ownly exposes

An endpoint that returns a masked number and OTP.

Order life cycle

The calls an order passes through, in order. The last two rows are alternatives that can end an order early.

Order delivery flow between the Ownly system and the downstream systemOwnly SystemDownstream SystemPush New OrderProcess New OrderOrderAcceptanceOrder CancelCancellationAcceptedOrder AcknowledgementSend AcknowledgementOrder CancellationProcess Order CancellationProcess Food Ready StatusFood ReadyProcess Rider AssignmentProcess Rider AssignmentProcess Rider DispatchProcess Rider DispatchProcess Rider DeliveredProcess Rider Delivered
StepSent from and toCall and value
Order placedOwnly→Your POSPOST /api/v1/order/
Sends status: placed
Order acceptedYour POS→OwnlyPOST /api/v1/order-status
Sends RESTAURANT_ACCEPTED
Food readyYour POS→OwnlyPOST /api/v1/order-status
Sends FOOD_READY
Rider assignedOwnly→Your POSPOST <upstream-host>/api/v1/rider-status
Sends RIDER_ASSIGNED
Rider at storeOwnly→Your POSPOST <upstream-host>/api/v1/rider-status
Sends RIDER_AT_STORE
Out for deliveryOwnly→Your POSPOST <upstream-host>/api/v1/rider-status
Sends OUT_FOR_DELIVERY
Reached drop locationOwnly→Your POSPOST <upstream-host>/api/v1/rider-status
Sends REACHED_DROP_LOCATION
DeliveredOwnly→Your POSPOST <upstream-host>/api/v1/rider-status
Sends DELIVERED
Restaurant cancels AlternativeYour POS→OwnlyPOST /api/v1/order-status
Sends RESTAURANT_CANCELLED
Customer cancels AlternativeOwnly→Your POSPOST /api/v1/order-status
Sends CUSTOMER_CANCELLED

Ready to build? Open the API reference.

API reference.

The Ownly API is organised around REST. Every call, grouped by what it manages.

Conventions

Request and response bodies in the samples are JSON. Examples that name a host use https://api.baseurl.com as a placeholder; replace it with the base URL for your integration. Rider status is the exception: it lives on your own host, shown as <upstream-host>.

Success

200A JSON body with a message.

Failure

400A JSON body with an error message. The field is error or message as each contract shows.

Auth

The key header on most calls, Authorization on inventory. See Authentication.

Endpoints by group

Looking for one call? Search all endpoints by path, name or parameter.

Menu push.

Send the complete menu for a restaurant. Ownly queues it, processes it asynchronously and calls your callbackUrl when it finishes.

POST/api/v1/menu
Ownly hosts thisEvery push replaces the existing menu. There are no partial updates.

Request headers

HeaderDescription
keyAuth key

Request body

ParameterTypeDescriptionRequired
restaurantRestaurant objectInformation about the restaurant, such as id and opening timings.Required
categoriesCategory object[]Menu categories, each containing items or subcategories.Required
variantGroupsVariant group object[]Sets of customisable options for menu items, such as sizes or flavours.Required
variantsVariant object[]The individual variants associated with menu items.Required
billComponentsBill components objectThe charges and taxes referenced across the menu.Required
callbackUrlstringCalled when asynchronous processing completes. See Callback.Required
timingsTiming object[]Timings that categories, items and the restaurant reference by id.Optional
orderBillComponentsOrder bill components objectCharge ids applicable on the order. Taxes are not applied directly on the order.Optional
addOnGroupsAdd-on group object[]Groups of add-ons, such as extra toppings or sides, that customers can select when customising items.Optional
metaMeta objectOptional metadata for the unified menu payload.Optional

Objects

Restaurant

ParameterTypeDescriptionRequired
idstringId of the restaurant.Required
minPrepTimeintMinimum prep time of the restaurant.Optional
timingsstringId of the timing.Optional

Category

ParameterTypeDescriptionRequired
idstringA unique identifier for the category.Required
namestringThe name of the category, for example "South Indian Meals", "Beverages" or "Soups".Required
descriptionstringA brief description of the category.Optional
imageUrlstringThe URL of an image representing the category.Optional
sortOrderintegerThe order in which categories appear.Required
itemsItem object[]The menu items under the category. Required when there are no subcategories.Conditional
subcategoriesCategory object[]Subcategories such as "Hot Beverages" and "Cold Beverages" under "Beverages". Required when there are no items.Conditional
timingsstringCategory availability timing id. If left blank, the category is enabled all day, all week.Optional
Items or subcategories, never both. A category holds either items or subcategories. They must not coexist under the same category.

Item

ParameterTypeDescriptionRequired
idstringA unique identifier for the menu item.Required
namestringThe name of the menu item, like "Margherita Pizza".Required
descriptionstringA detailed description of the item.Optional
imageUrlstringA link to an image of the item.Required
pricefloatThe base price of the item, such as 200.50 rupees for a Margherita Pizza.Required
markupPricefloatAn optional higher price to strike off.Optional
inStockbooleanWhether the item is available. true means in stock.Required
recommendedbooleanWhether the item is recommended, for example the restaurant's signature dish.Optional
isFavoritebooleanWhether the item is marked as a favourite by customers.Optional
foodTypestringOne of veg, non veg, egg, vegan.Required
tagsstring[]Keywords associated with the item, like "Spicy" or "Gluten-Free".Optional
variantGroupIdsstring[]Ids linking the item to variant groups. For example, a pizza linked to a "Size" group.Optional
addOnGroupIdsstring[]Ids linking the item to add-on groups, such as "Extra Cheese" or "Dips".Optional
nutritionalInfoNutritional info objectDetailed nutrition details.Optional
billComponentsItem bill components objectItem-specific billing components, such as a "Packing Charge" and taxes.Required
fulfillmentModesstring[]Supported modes. Currently delivery.Required
sortOrderintegerThe display order. 1 is shown at the top of the category.Required
categoryIdstringId of the parent category.Required
subcategoryIdstringId of the parent subcategory.Optional
ignoreOnIgnore on objectWhat to ignore for the item while billing, for example tax.Optional
gstTypestringWhether the item carries the goods tax type (restaurant liable) or the services tax type (Ownly liable).Optional
timingsstringItem availability timing id. If left blank, the item is enabled all day, all week.Optional

Variant group

ParameterTypeDescriptionRequired
idstringA unique identifier for the variant group.Required
namestringThe name of the group, such as "Size" or "Crust Type".Required
variantIdsstring[]Ids linking the group to its variants. A "Size" group may reference "Small", "Medium" and "Large".Required
sortOrderintegerThe display order of the group among an item's customisation options.Required

Variant

ParameterTypeDescriptionRequired
idstringA unique identifier for the variant.Required
namestringThe name of the variant, such as "Large", "Thin Crust" or "Extra Spicy".Required
pricefloatThe price of the variant. For instance, 550.25 rupees for a large pizza.Required
markupPricefloatAn optional higher price for premium variants.Optional
inStockbooleanWhether the variant is available.Required
foodTypestringOne of veg, non veg, egg, vegan.Required
addOnGroupIdsstring[]Links the variant to add-on groups. For example, a "Dips" group for pizza variants.Optional
nutritionalInfoNutritional info objectNutritional details for the variant.Optional
fulfillmentModesstring[]Supported modes. Currently delivery.Required
variantGroupIdsstring[]Links the variant to its parent group. For example, "Large" belongs to the "Size" group.Required
billComponentsItem bill components objectBilling components for the variant, such as packing charges.Optional
sortOrderintegerThe display order.Required

Add-on group

ParameterTypeDescriptionRequired
idstringA unique identifier for the add-on group.Required
namestringThe name of the group, such as "Dips", "Extra Toppings" or "Drinks".Required
minimumNeededintegerThe minimum number of selections required. A "Toppings" group might require at least 1.Required
maximumAllowedintegerThe maximum number of selections allowed. A "Dips" group might allow up to 3.Required
addOnsAdd-on object[]The available add-ons, such as "Mushrooms", "Olives" and "Jalapeños".Required
sortOrderintegerThe display order.Required

Add-on

ParameterTypeDescriptionRequired
idstringA unique identifier for the add-on.Required
namestringThe name of the add-on, such as "Extra Cheese", "BBQ Sauce" or "Garlic Bread".Required
pricefloatThe price of the add-on. For example, 20 rupees for "Extra Cheese".Required
inStockbooleanWhether the add-on is available.Required
foodTypestringThe type of food, such as "Veg", "Non-Veg" or "Egg". A bacon add-on would be marked "Non-Veg".Required
nutritionalInfoNutritional info objectDetailed nutritional information.Optional
fulfillmentModesstring[]How the add-on can be ordered.Required
sortOrderintegerThe display order.Required
imageUrlstringImage URL.Optional

Item bill components

ParameterTypeDescriptionRequired
chargesstring[]Charge identifiers applicable to the item.Required
taxIdsstring[]Tax identifiers.Required

Nutritional info

Nutrient fields take a Nutritional value object. The samples send value and unit.

ParameterTypeDescriptionRequired
carbohydrateNutritional value objectThe carbohydrate content, for example 30g in a serving of pasta.Optional
fiberNutritional value objectThe dietary fibre content, for example 5g in a salad bowl.Optional
proteinNutritional value objectThe protein content, for example 20g in a chicken breast.Optional
calorieNutritional value objectThe total caloric value, for example 400 kcal for a slice of pizza.Optional
sodiumNutritional value objectThe sodium content, for example 200mg in a bowl of soup.Optional
cholesterolNutritional value objectThe cholesterol content, for example 50mg in a cheese sandwich.Optional
foodAmountNutritional value objectThe amount of food. Provide it in g, kg, ml or l.Optional
mineralsNutritional value objectMineral content, like 50mg of calcium or 20mg of iron.Optional
totalSugarNutritional value objectThe total sugar content, such as 10g in a cookie.Optional
addedSugarNutritional value objectThe sugar added during preparation, for instance 5g in a soft drink.Optional
totalFatNutritional value objectThe total fat content, such as 15g in a burger.Optional
saturatedFatNutritional value objectThe saturated fat content, for instance 5g in a croissant.Optional
transFatNutritional value objectThe trans fat content, for example 1g in deep-fried snacks.Optional
vitaminsNutritional value objectVitamin content, like Vitamin C (20mg) or Vitamin D (5mg).Optional
servingInfostringAdditional serving information, such as "1 cup" or "2 pieces".Optional
additiveMapobjectDetails about additives, such as "Contains artificial sweeteners".Optional
allergensAllergen info objectInformation about allergens, for example "Contains peanuts".Optional
additionalInfoAdditional info objectAny other relevant details, like "Gluten-free" or "Low sodium".Optional
saltNutritional value objectThe salt content, for instance 1.5g in chips.Optional

Nutritional value

ParameterTypeDescriptionRequired
valuefloatThe numerical value of the nutrient. For instance, 200 for calories.Optional
unitstringThe unit of measurement, such as g, mg or kcal.Optional
namestringThe name of the nutrient, such as "Protein" or "Vitamin A".Optional

Allergen info

ParameterTypeDescriptionRequired
allergenstringThe name of the allergen, for example "Peanuts", "Gluten" or "Dairy".Optional
allergenDescstringA description, for instance "Contains peanuts as an ingredient in the sauce".Optional

Additional info

ParameterTypeDescriptionRequired
infostringAny additional information, for example "This dish is part of the Keto diet".Optional
remarkstringRemarks or warnings, for instance "Spicy level: High".Optional

Bill components

ParameterTypeDescriptionRequired
chargesCharge object[]Additional charges, such as "Packaging Fee (35 rupees)".Required
taxesTax object[]A list of taxes.Required

Order bill components

ParameterTypeDescriptionRequired
chargesstring[]Charge identifiers.Required

Charge

ParameterTypeDescriptionRequired
idstringA unique identifier for the charge.Required
namestringThe name of the charge, such as "Delivery Fee" or "Convenience Charge".Required
descriptionstringAdditional details about the charge.Optional
valuefloatThe value of the charge.Required
typestringThe type of charge: FIXED (for example 20 rupees per order) or PERCENTAGE (for example 5% of the order total).Optional
fulfillmentModesstring[]Where the charge applies. Currently delivery.Required
taxesstring[]Applicable tax ids. For example, a "Service Charge" might have "TAX002" applied.Required

Tax

ParameterTypeDescriptionRequired
idstringA unique identifier for the tax.Required
namestringThe name of the tax, such as "CGST" or "SGST".Optional
descriptionstringAdditional details about the tax. For example, "Applies to all food items".Required
valuefloatThe tax rate. For instance, 2.5% for CGST.Required
fulfillmentModesstring[]Where the tax is applicable.Required

Timing

ParameterTypeDescriptionRequired
idstringA unique identifier for the timing.Required
daysDay object[]Day-wise availability. For example, "Breakfast: Mon-Fri" and "Dinner: Sat-Sun".Required

Day

ParameterTypeDescriptionRequired
daystringThe day of the week, for instance "Monday" or "Tuesday".Required
slotsSlot object[]Time slots for the day. For example, breakfast on Monday might be 08:00 to 11:00.Required

Slot

ParameterTypeDescriptionRequired
startTimestringStart of the slot in HH:MM, 24-hour. For example "09:00".Required
endTimestringEnd of the slot in HH:MM, 24-hour. For example "11:30".Required

Ignore on

ParameterTypeDescriptionRequired
taxboolWhether to consider tax on the item for billing. If true, no tax is added for the item.Optional
discountsboolWhether the item is excluded from discounts. If true, a premium dish marked "Chef's Special" receives no discounts, even during promotions.Optional

Meta

ParameterTypeDescriptionRequired
rxLocationRxLocation objectOptional restaurant location coordinates.Optional

RxLocation

ParameterTypeDescriptionRequired
latitudestringLatitude coordinate.Optional
longitudestringLongitude coordinate.Optional

Callback

Menu processing is queued and handled asynchronously. Each request is tracked by a unique request id. When Ownly finishes, it calls the callbackUrl from your payload, for example https://<external-host>/callback/<req_id>, with the completion status and the results for that requestId.

Callback request body

ParameterTypeDescriptionRequired
requestIdstringRequest id of the queued menu processing.Required
successboolStatus of the request.Required
errorMsgsstring[]Generic error messages.Optional
dataError object[]Resources that failed, with the type of error, the id of the catalogue entity and the reason.Optional

Error

ParameterTypeDescriptionRequired
resourceIdstringId of the resource that failed.Required
typestringResource type. One of category, subcategory, item, variantGroup, addonGroup, variant, addon, tax, charge.Required
reasonstringThe reason it failed.Required
Callback on success
{
    "requestId": "c746a5cbeae74287b5b959b68a5f4d5d",
    "success": true
}
Callback on failure
    "requestId": "c746a5cbeae74287b5b959b68a5f4d5d",
    "success": false,
    "data": [
        {
            "type": "item",
            "resourceId": "7011688",
            "reason": "item price cannot be negative"
        },
        {
            "type": "tax",
            "resourceId": "12764",
            "reason": "tax value cannot be negative"
        }
    ]
}

Sample request

The full sample, as Ownly accepts it. Scroll inside the block to read it all.

Request
POST /api/v1/menu
key: <your-auth-key>

{
    "restaurant": {
        "id": "53349"
    },
    "categories": [
        {
            "id": "139714",
            "name": "Best in Pizza",
            "description": "Best in Pizza",
            "imageUrl": "http://image.jpg",
            "sortOrder": 7,
            "items": [],
            "subcategories": [
                {
                    "id": "139716",
                    "name": "New Pizza",
                    "description": "New Pizzas everyday",
                    "imageUrl": "http://image.jpg",
                    "sortOrder": 1,
                    "items": [
                        {
                            "id": "701172",
                            "name": "Paneer Pizza",
                            "description": "spicy panner pizza",
                            "imageUrl": "http://img.jpg",
                            "price": 139,
                            "markupPrice": 199.9,
                            "inStock": true,
                            "recommended": false,
                            "foodType": "non veg",
                            "tags": [
                                "spicy"
                            ],
                            "variantGroupIds": [
                                "440072"
                            ],
                            "addonGroupIds": [
                                "440084"
                            ],
                            "nutritionalInfo": {
                                "carbohydrate": {
                                    "unit": "mg/g",
                                    "value": 1.1
                                },
                                "fiber": {
                                    "unit": "mg",
                                    "value": 60.0
                                },
                                "fat": {
                                    "unit": "mg",
                                    "value": 30.0
                                },
                                "protein": {
                                    "unit": "mg",
                                    "value": 10.0
                                },
                                "calorie": {
                                    "unit": "kcal",
                                    "value": 1.1
                                }
                            },
                            "billComponents": {
                                "charges": [
                                    "7795"
                                ],
                                "taxIds": [
                                    "12761",
                                    "12762",
                                    "12814",
                                    "12815"
                                ]
                            },
                            "fulfillmentModes": [
                                "delivery"
                            ],
                            "sortOrder": 5,
                            "categoryId": "139714",
                            "subcategoryId": "139716",
                            "ignoreOn": {
                                "tax": false
                            }
                        }
                    ]
                }
            ],
            "timings": "58681"
        },
        {
            "id": "134715",
            "name": "All New",
            "imageUrl": "http://image.jpg",
            "sortOrder": 1,
            "items": [
                {
                    "id": "7021727",
                    "name": "Chicke  tikka",
                    "description": "Delicious chicken tikka",
                    "imageUrl": "http://image.jpg",
                    "price": 139,
                    "inStock": true,
                    "recommended": false,
                    "foodType": "non veg",
                    "tags": [
                        "info-services"
                    ],
                    "variantGroupIds": [],
                    "addonGroupIds": [],
                    "nutritionalInfo": {},
                    "billComponents": {
                        "charges": [
                            "7795"
                        ],
                        "taxIds": [
                            "12761",
                            "12762",
                            "12814",
                            "12815"
                        ]
                    },
                    "fulfillmentModes": [
                        "delivery"
                    ],
                    "sortOrder": 35,
                    "categoryId": "134715",
                    "subcategoryId": "132716"
                }
            ]
        }
    ],
    "timings": [
        {
            "id": "58681",
            "days": [
                {
                    "day": "Monday",
                    "slots": [
                        {
                            "startTime": "06:00",
                            "endTime": "11:00"
                        }
                    ]
                },
                {
                    "day": "Tuesday",
                    "slots": [
                        {
                            "startTime": "06:00",
                            "endTime": "11:00"
                        }
                    ]
                },
                {
                    "day": "Wednesday",
                    "slots": [
                        {
                            "startTime": "06:00",
                            "endTime": "11:00"
                        }
                    ]
                },
                {
                    "day": "Thursday",
                    "slots": [
                        {
                            "startTime": "06:00",
                            "endTime": "11:00"
                        }
                    ]
                },
                {
                    "day": "Friday",
                    "slots": [
                        {
                            "startTime": "06:00",
                            "endTime": "11:00"
                        }
                    ]
                },
                {
                    "day": "Saturday",
                    "slots": [
                        {
                            "startTime": "06:00",
                            "endTime": "11:00"
                        }
                    ]
                },
                {
                    "day": "Sunday",
                    "slots": [
                        {
                            "startTime": "06:00",
                            "endTime": "11:00"
                        }
                    ]
                }
            ]
        },
        {
            "id": "58719",
            "days": [
                {
                    "day": "Wednesday",
                    "slots": [
                        {
                            "startTime": "11:30",
                            "endTime": "16:00"
                        }
                    ]
                }
            ]
        }
    ],
    "orderBillComponents": {
        "charges": [
            {
                "id": "7796",
                "name": "Order level Charge",
                "description": "",
                "value": 30,
                "type": "FIXED",
                "taxes": [
                    "12763"
                ]
            }
        ]
    },
    "addonGroups": [
        {
            "id": "440084",
            "name": "Amazing Desserts",
            "minimumNeeded": 0,
            "maximumAllowed": 10,
            "sortOrder": 3,
            "addOns": [
                {
                    "id": "1595275",
                    "name": "Chocolate",
                    "price": 139,
                    "inStock": true,
                    "foodType": "veg",
                    "sortOrder": 1,
                    "imageUrl": "http://image.jpg"
                },
                {
                    "id": "1295275",
                    "name": "Chicken Sausage",
                    "price": 39,
                    "inStock": true,
                    "foodType": "non Veg",
                    "nutritionalInfo": {},
                    "sortOrder": 2,
                    "imageUrl": "http://image.jpg"
                }
            ]
        },
        {
            "id": "450102",
            "name": "Toppings",
            "minimumNeeded": 0,
            "maximumAllowed": 1,
            "sortOrder": 1,
            "addOns": [
                {
                    "id": "1535340",
                    "name": "Chicken ",
                    "price": 0,
                    "inStock": true,
                    "foodType": "veg",
                    "sortOrder": 146,
                    "imageUrl": ""
                }
            ]
        },
        {
            "id": "460102",
            "name": "Choose One Cheese Burst Flavor (r)",
            "minimumNeeded": 0,
            "maximumAllowed": 1,
            "sortOrder": 1,
            "addOns": [
                {
                    "id": "1565340",
                    "name": "Cheesy Cheese Burst",
                    "price": 0,
                    "inStock": true,
                    "foodType": "veg",
                    "sortOrder": 246,
                    "imageUrl": ""
                }
            ]
        }
    ],
    "variantGroups": [
        {
            "id": "440072",
            "name": "Base",
            "variantIds": [
                "1595518",
                "1695518"
            ],
            "sortOrder": 1
        },
        {
            "id": "470072",
            "name": "Size",
            "variantIds": [
                "1395518",
                "1495518"
            ],
            "sortOrder": 0
        },
        {
            "id": "570072",
            "name": "Size",
            "variantIds": [
                "2495518"
            ],
            "sortOrder": 0
        }
    ],
    "variants": [
        {
            "id": "1595518",
            "name": "crust",
            "price": 429,
            "inStock": true,
            "foodType": "veg",
            "variantGroupIds": [
                "470072"
            ],
            "addonGroupIds": [],
            "billComponents": {
                "charges": ["779123"]
            },
            "sortOrder": 0
        },
        {
            "id": "1395518",
            "name": "Regular",
            "price": 429,
            "inStock": true,
            "foodType": "veg",
            "addonGroupIds": [
                "460102"
            ],
            "sortOrder": 0
        },
        {
            "id": "1495518",
            "name": "Large",
            "price": 529,
            "inStock": true,
            "foodType": "veg",
            "sortOrder": 1,
            "addonGroupIds": [
                "450102"
            ]
        },
        {
            "id": "1695518",
            "name": "pan",
            "price": 129,
            "inStock": true,
            "foodType": "veg",
            "nutritionalInfo": {},
            "variantGroupIds": [
                "570072"
            ],
            "sortOrder": 1,
            "addonGroupIds": null
        },
        {
            "id": "2495518",
            "name": "Large",
            "price": 729,
            "inStock": true,
            "foodType": "veg",
            "addonGroupIds": null,
            "sortOrder": 0
        }
    ],
    "billComponents": {
        "charges": [
            {
                "id": "7795",
                "name": "Packing Charge",
                "description": "",
                "value": 20,
                "type": "FIXED",
                "fulfillmentModes": [
                    "delivery"
                ],
                "taxes": [
                    "12764"
                ]
            },
            {
                "id": "7796",
                "name": "Handling Charge",
                "description": "",
                "value": 30,
                "type": "FIXED",
                "fulfillmentModes": null,
                "taxes": [
                    "12763"
                ]
            }
        ],
        "taxes": [
            {
                "id": "12761",
                "name": "CGST",
                "description": "",
                "value": 2.5,
                "fulfillmentModes": null
            },
            {
                "id": "12762",
                "name": "SGST",
                "description": "",
                "value": 2.5,
                "fulfillmentModes": null
            },
            {
                "id": "12763",
                "name": "Delivery Charge Tax",
                "description": "",
                "value": 18,
                "fulfillmentModes": null
            },
            {
                "id": "12764",
                "name": "Packing Charge",
                "description": "",
                "value": 5,
                "fulfillmentModes": null
            },
            {
                "id": "12814",
                "name": "SGST",
                "description": "",
                "value": 2.5,
                "fulfillmentModes": null
            },
            {
                "id": "12815",
                "name": "CGST",
                "description": "",
                "value": 2.5,
                "fulfillmentModes": null
            }
        ]
    },
    "callbackUrl": "https://host.com/request-id",
    "meta": {
        "rxLocation": {
            "latitude": "12.9716",
            "longitude": "77.5946"
        }
    }
}

Responses

200 Success
{
    "message": "Menu published successfully"
}
400 Error
{
    "message": "error message",
    "code": "400"
}

Inventory update.

Update the stock status of items, variants and add-ons in Ownly. Use it to mark things out of stock, and to say when they return.

POST/api/v1/item-status
Ownly hosts thisOne call applies the same inStock value to every item, variant and add-on you list.

Request headers

HeaderDescription
AuthorizationBasic Auth

Request body

ParameterTypeDescriptionRequired
restIdstringThe unique identifier for the restaurant.Required
itemsstring[]Menu item identifiers whose stock status is changing.Required
variantsstring[]Variant identifiers whose stock status needs an update.Required
addOnsstring[]Add-on identifiers whose stock status needs an update.Required
inStockbooleanThe availability status. true means available, false means out of stock. Applies to all specified items, variants and add-ons.Required
nextAvailableAtintegerUnix timestamp in milliseconds (13 digits) for when the out-of-stock items will be restocked.
Note: We kindly recommend managing stock restoration directly from your side.
Optional

Sample request

Request
POST /api/v1/item-status
Authorization: Basic <credentials>

{
    "restId": "53349",
    "addOns": [
        "1595275"
    ],
    "inStock": false,
    "items": [
        "701172"
    ],
    "variants": [
        "1595518"
    ],
    "nextAvailableAt": 1717209600000
}

Responses

200 Success
{
    "message": "Item Inventory updated successfully"
}
400 Error
{
    "error": "error message"
}

Order relay.

Ownly relays every new order to your system. Expose this endpoint and Ownly will call it each time a customer places an order.

POST/api/v1/order/
Your POS hosts thisOwnly calls your host with the full order.

Request headers

HeaderDescription
keyKey

Request body

ParameterTypeDescriptionRequired
orderInfoOrder info objectThe key details about the order itself: order id, restaurant id, order type, discounts, and charges like subtotal, taxes and total. It also carries payment mode, preparation time and delivery mode.Required
paymentPayment objectThe payment details: the method (for example cash, card or UPI), the status (paid or unpaid) and the amounts.Required
customerCustomer objectDetails about the customer placing the order: first name, last name and an optional masked phone number.Required
itemsItem object[]The individual menu items in the order, including item id, name, quantity, price and associated charges or instructions.Required
otpOTP objectOne-time passwords for pickup and drop verification.Optional
prepTimeDetailsPrep time details objectPredicted kitchen preparation time and the allowed adjustment thresholds. Omitted when not provided.Optional

Objects

Order info

ParameterTypeDescriptionRequired
orderIdstringThe unique identifier for the order.Required
restIdstringThe unique identifier for the restaurant.Required
instructionstringSpecial instructions from the customer, for example "Please make it extra spicy".Optional
statusstringThe current status of the order. Always placed here.Required
subTotalfloatThe total price of the items excluding taxes and charges. When items have itemDiscounts, it is the total at listed prices, before item discounts.Required
totalPackingChargefloatTotal charge for packing collected.Optional
totalTaxesfloatThe total tax amount.Required
createdAtintThe Unix timestamp when the order was placed.Required
totalfloatThe total amount: total = subtotal + charges + taxes.Required
deliveryModestringThe mode of delivery. One of self_delivery, delivery.Optional
discountsDiscount object[]Order-level discounts applied to the order. Omitted when none exist.Optional

Discount

ParameterTypeDescriptionRequired
scopestringWhere the discount applies. CART applies to the entire cart and order total. ITEM is reserved: item-level discounts are not sent here, they are sent in items[].itemDiscounts.Required
valuefloatThe discount value. Its meaning depends on type.Required
typestringHow value is read. PERCENTAGE: value is the percentage (10 means 10% off). FIXED: value is the amount in currency units (50.9 means ₹50.90 off).Required

Payment

ParameterTypeDescriptionRequired
modestringThe mode of payment used. For example, "online".Required
statusstringThe current payment status. Possible value: paid.Required
amountPaidfloatThe amount paid by the customer. For example, 500.00 rupees.Required

Customer

ParameterTypeDescriptionRequired
firstNamestringThe customer's first name. For example, "John".Required
lastNamestringThe customer's last name. For example, "Doe".Required
phoneNumberstringCustomer phone, as a masked number (partially redacted for privacy).Optional

OTP

ParameterTypeDescriptionRequired
pickupintegerOTP for pickup verification.Optional
dropintegerOTP for drop-off verification.Optional

Prep time details

ParameterTypeDescriptionRequired
predictedPrepTimeintegerInitial kitchen preparation time in minutes. For example, 15.Optional
maxIncreaseThresholdintegerMaximum minutes the restaurant may increase predictedPrepTime. Allowed maximum is predictedPrepTime + maxIncreaseThreshold (15 + 3 = 18).Optional
maxDecreaseThresholdintegerMaximum minutes the restaurant may decrease predictedPrepTime. Allowed minimum is predictedPrepTime − maxDecreaseThreshold (15 − 5 = 10).Optional

If prepTimeDetails is omitted, continue with the existing preparation time workflow.

Item

ParameterTypeDescriptionRequired
itemIdstringThe unique identifier for the item.Required
namestringThe name of the item. For example, "Chicken Biryani".Required
quantityintegerThe quantity of the item. For example, 2.Required
unitPricefloatThe price per unit, for example 250.00 rupees. This is the listed price, before any discount. When the item has itemDiscounts, the discount is not applied to unitPrice; it is given separately in itemDiscounts.Required
taxesTaxes object[]The tax details for the item.Required
chargesCharges object[]Additional charges applicable for the item.Required
instructionstringSpecial instructions for the item. For example, "Extra Spicy".Optional
variantsVariants object[]The variant details for the item, for example size or type.Conditional
addOnsAdd-on object[]Add-ons associated with the item.Conditional
itemDiscountsItem discount object[]Discounts applied to this item and its variants. Omitted when the item has no discount. At most one entry per item. Not repeated in orderInfo.discounts.Optional

Item discount

ParameterTypeDescriptionRequired
idstringThe unique identifier of the offer that produced the discount.Required
titlestringThe display name of the offer. For example, "First Off".Required
modestringHow the offer is configured: PERCENTAGE or FIXED. Informational only; use amount for the discount value.Required
valuefloatThe configured discount: a percentage when mode is PERCENTAGE (20 means 20% off), or an amount in currency units when FIXED. Informational only.Required
amountfloatTotal discount for the whole line, in currency units: the item plus all its discounted variants, multiplied by quantity. Equals itemAmount + variantAmount. This is the amount to subtract from the item subTotal.Required
itemAmountfloatThe part of amount that comes from the base item, multiplied by quantity.Required
variantAmountfloatThe part of amount that comes from the item's variants, including nested variants, multiplied by quantity. 0 when no variant is discounted.Required
How item discounts add up
  • For an item with itemDiscounts, unitPrice (item and variants) and the item subTotal are the listed prices before the discount. The amount charged for the line is subTotal − amount.
  • The item total is subTotal − amount + item taxes. Taxes are calculated on the discounted amount.
  • orderInfo.subTotal is the sum of the item subTotal values, before item discounts. orderInfo.total is the amount payable: total = subTotal − item discounts − order-level (CART) discounts + taxes + charges.
  • Discounted variants carry their own discountAmount. Add-ons are not discounted.
  • Item-level discounts are never aggregated into orderInfo.discounts, which only carries order-level (CART) discounts.
  • Items without a discount are unchanged: no itemDiscounts, and the prices are the charged prices.

Variants

ParameterTypeDescriptionRequired
idstringThe unique identifier for the variant.Required
namestringThe name of the variant. For example, "Large".Optional
unitPricefloatThe price of the variant, for example 100.00 rupees. This is the listed price, before any discount.Required
discountAmountfloatThe discount on this variant for the whole line: the per-unit discount × item quantity. Present only when the variant is discounted. The sum over all variants equals variantAmount in the Item discount object.Optional
variantsVariants object[]Nested variant details.Conditional
addOnsAdd-on object[]Additional add-ons associated with the variant.Conditional

Add-on

ParameterTypeDescriptionRequired
idstringThe unique identifier for the add-on.Required
namestringThe name of the add-on. For example, "Extra Cheese".Required
unitPricefloatThe price of the add-on. For example, 50.00 rupees.Required

Taxes

ParameterTypeDescriptionRequired
titlestringThe name of the tax. For example, "SGST".Required
valuefloatThe tax amount. For example, 25.00 rupees.Required
percentagefloatThe tax percentage. For example, 2.50.Required
liabilityOnstringrestaurant or aggregator.Required

Charges

ParameterTypeDescriptionRequired
titlestringThe name of the charge. For example, "Delivery Charge".Required
valuefloatThe amount of the charge. For example, 30.00 rupees.Required
liability_onstringrestaurant or aggregator.Required

Sample request

Request
POST /api/v1/order/
key: <key>

{
  "orderInfo": {
    "orderId": "ORD123456",
    "restId": "REST1001",
    "instruction": "Make it spicy",
    "status": "placed",
    "subTotal": 500.0,
    "totalPackingCharge": 20.0,
    "totalTaxes": 45.0,
    "createdAt": 1717046400,
    "total": 565.0,
    "deliveryMode": "delivery",
    "discounts": [
      {
        "scope": "CART",
        "value": 10,
        "type": "PERCENTAGE"
      }
    ]
  },
  "payment": {
    "mode": "online",
    "status": "paid",
    "amountPaid": 565.0
  },
  "customer": {
    "firstName": "John",
    "lastName": "Doe",
    "phoneNumber": "98******10"
  },
  "otp": {
    "pickup": 1234,
    "drop": 1244
  },
  "prepTimeDetails": {
    "predictedPrepTime": 15,
    "maxIncreaseThreshold": 3,
    "maxDecreaseThreshold": 5
  },
  "items": [
    {
      "itemId": "ITEM001",
      "name": "Chicken Biryani",
      "quantity": 2,
      "unitPrice": 312.5,
      "instruction": "Extra Spicy",
      "itemDiscounts": [
        {
          "id": "OFFER001",
          "title": "First Off",
          "mode": "PERCENTAGE",
          "value": 20,
          "amount": 175.0,
          "itemAmount": 125.0,
          "variantAmount": 50.0
        }
      ],
      "taxes": [
        {
          "title": "SGST",
          "value": 12.5,
          "percentage": 2.5,
          "liability_on": "restaurant"
        },
        {
          "title": "CGST",
          "value": 12.5,
          "percentage": 2.5,
          "liability_on": "restaurant"
        }
      ],
      "charges": [
        {
          "title": "Packing Charge",
          "value": 10.0,
          "liability_on": "restaurant"
        }
      ],
      "variants": [
        {
          "id": "VAR001",
          "name": "Family Pack",
          "unitPrice": 125.0,
          "discountAmount": 50.0,
          "variants": [],
          "addOns": [
            {
              "id": "ADDON001",
              "name": "Extra Raita",
              "unitPrice": 20.0
            }
          ]
        }
      ],
      "addOns": [
        {
          "id": "ADDON002",
          "name": "Extra Salad",
          "unitPrice": 15.0
        }
      ]
    }
  ]
}

Responses

200 Success
{
    "message": "Order Details successfully communicated."
}
400 Error
{
    "error": "error message"
}

Order status exchange.

Both systems expose this endpoint to exchange an order's status. Your POS sends acceptance, cancellation and food ready; Ownly sends customer cancellation.

POST/api/v1/order-status
Both systems host thisRestaurant cancellation after acceptance uses this same endpoint.

Request headers

HeaderDescription
keyKey

Request body

ParameterTypeDescriptionRequired
orderIdstringThe Ownly order id.Required
restIdstringThe restaurant id.Optional
statusstringThe new status of the order. See Status values.Required
reasonstringCancellation reason code. Required when status is RESTAURANT_CANCELLED. See Cancellation reason.Conditional
reasonDetailsstringFree-text cancellation details. Required when reason is other. Must not be sent for any other reason.Conditional
finalPrepTimeintegerFinal kitchen preparation time in minutes selected by the restaurant. Sent with RESTAURANT_ACCEPTED. When prepTimeDetails was present on the order, the value must stay within predictedPrepTime ± the given thresholds.Optional

Status values

ValueSent byMeaning
RESTAURANT_ACCEPTEDYour POSThe restaurant accepted the order.
RESTAURANT_CANCELLEDYour POSThe restaurant cancelled the order. Requires a reason.
FOOD_READYYour POSThe food is ready.
CUSTOMER_CANCELLEDOwnlyThe customer cancelled the order.

Cancellation reason

ValueMeaning
item_out_of_stockOne or more items required for the order are unavailable.
store_closedThe restaurant is closed.
store_busyThe restaurant cannot fulfil the order due to high load.
otherThe cancellation does not match any predefined reason.
Validation rules
  • reason is mandatory for a cancellation.
  • Only the documented enum values are accepted.
  • reasonDetails is mandatory, and must be a non-empty string, when reason is other.

Sample requests

Restaurant accepted
POST /api/v1/order-status
key: <key>

{
  "orderId": "1783513160580978958",
  "restId": "10454115",
  "status": "RESTAURANT_ACCEPTED",
  "finalPrepTime": 18
}
Standard cancellation reason
POST /api/v1/order-status
key: <key>

{
  "orderId": "1783513160580978958",
  "restId": "10454115",
  "status": "RESTAURANT_CANCELLED",
  "reason": "item_out_of_stock"
}
Other cancellation reason
POST /api/v1/order-status
key: <key>

  "orderId": "1783513160580978958",
  "restId": "10454115",
  "status": "RESTAURANT_CANCELLED",
  "reason": "other",
  "reasonDetails": "Kitchen equipment is not operational"
}

Responses

200 Success
{
    "message": "Order Status exchanged successfully"
}
400 Error
{
    "message": "error message"
}

Call masking.

Retrieve a masked contact number and OTP to start a call between two entities for an order. The from and to query parameters name who is calling whom.

GET/api/v1/contact
Ownly hosts thisPass the order id and the two entities as query parameters.

Request headers

HeaderDescription
keyKey
Acceptapplication/json

Query parameters

ParameterTypeDescriptionRequired
orderIdstringUnique string identifier for the order. For example, "17277272828828".Required
fromstringOrigin entity initiating the contact. For example, "restaurant".Required
tostringTarget entity receiving the contact. For example, "customer".Required

Response body

ParameterTypeDescriptionRequired
numberstringMasked contact number for the call.Required
otpstring6-digit PIN for call verification.Required

Sample request

cURL
curl --location 'https://api.baseurl.com/api/v1/contact?orderId=172282882929&from=restaurant&to=customer' \
--header 'Accept: application/json'

Responses

200 Success
{
  "number": "1234567890",
  "otp": "482901"
}
400 Error
{
    "error": "error message"
}

Rider status.

Ownly tells your system where the rider is on an order, from assignment to delivery. Expose this endpoint on your own host.

POST<upstream-host>/api/v1/rider-status
Your POS hosts thisOwnly calls your host as the order moves.

Request headers

HeaderDescription
keyKey

Request body

ParameterTypeDescriptionRequired
orderIdstringUnique identifier for the order for which the rider status is being updated.Required
statusstringThe current status of the rider for the order. See Status values.Required
riderDetailsRider details objectThe rider's name and phone number.Required

Status values

ValueMeaning
RIDER_ASSIGNEDA rider has been assigned to the order.
RIDER_AT_STOREThe rider has reached the store.
OUT_FOR_DELIVERYThe rider is on the way to the customer.
REACHED_DROP_LOCATIONThe rider has reached the drop location.
DELIVEREDThe order has been delivered.

Rider details

ParameterTypeDescriptionRequired
namestringThe name of the assigned rider. For example, "Ram" is the delivery executive handling the order.Required
phonestringThe phone number of the rider. For example, "98******10".Required

Sample request

Request
POST <upstream-host>/api/v1/rider-status
key: <key>

{
  "orderId": "10454115",
  "status": "OUT-FOR-DELIVERY",
  "riderDetails": {
    "name": "Ram",
    "phone": "9******210"
  }
}

Responses

200 Success
{
    "message": "Delivery Status updated successfully."
}
400 Error
{
    "error": "error message"
}

Store status.

Enable or disable a store on Ownly. Take a restaurant offline when the kitchen is closed or overwhelmed, and bring it back when it is ready.

POST/api/v1/store-status
Ownly hosts thisThe orderingEnabled flag decides whether the store accepts new orders.

Request headers

HeaderDescription
keyKey

Request body

ParameterTypeDescriptionRequired
restIdstringUnique identifier of the restaurant whose status is being updated.Required
orderingEnabledbooleanThe current status of the restaurant: whether it is accepting new orders. true means open for new orders.Required
nextAvailableAtintUnix timestamp, in seconds.Optional
reasonstringReason for store closure.Optional

Sample request

Request
POST /api/v1/store-status
key: <key>

{
    "restId": "b7hi36eg",
    "orderingEnabled": true
}

Responses

200 Success
{
    "message": "Restaurant status successfully updated."
}
400 Error
{
    "error": "error message"
}

All endpoints.

Filter by name, path or parameter. Each call is hosted by one side, except order status, which both host.

Change log.

Changes to the API contract and the documentation, newest first.

  • Added optional itemDiscounts in the Item object under Order relay to carry item-level discounts
  • Added optional discountAmount in the Variants object under Order relay
  • For items with itemDiscounts, unitPrice (item and variants) and subTotal are now the listed prices before the discount, and orderInfo.subTotal is the sum of those listed subtotals
  • Clarified that item-level discounts are not sent in orderInfo.discounts
  • Documented request headers (key) for Rider status update under Rider management
  • Added ioos object for collecting items and nextAvailableAt data in the restaurant cancellation call under Order status exchange
  • Added optional prepTimeDetails object (predictedPrepTime, maxIncreaseThreshold, maxDecreaseThreshold) at order root level in Order relay
  • Added optional finalPrepTime for RESTAURANT_ACCEPTED under Order status exchange
  • Added optional discounts in the Order info object under Order relay
  • Restaurant cancellation: API contract update for the reason enum and reasonDetails under Order status exchange
  • Added Call masking API (GET /api/v1/contact) under Order management
  • Added phoneNumber (masked) to the Customer object in Order relay
  • Added otp object (pickup, drop) at order root level in Order relay
  • Added support for the meta object for storing auto-acceptance during order status exchange
  • Added support for the meta object for storing rxLocation (restaurant latitude and longitude) in Menu push
  • Updated the riderDetails object in the Rider status API
  • Fixed the items field name in the Order relay sample request body
  • Changed riderData to riderDetails in the Rider status update API
  • Changed taxes to taxIds in the item bill component
  • Added gstType and timings in the item component
  • Updated the enums for the rider status and order status APIs