API reference · Orders

Quote an order

POST/v1/orders/quote

Billzova prices the cart with the same engine the POS bills with: items, add-ons, GST split, total. Show this total to the customer.

Scope orders:write
120 / minute

Body

type"PICKUP" | "DELIVERY"required: Order type. Must be enabled for the restaurant.
itemsarray (1–50)required: Cart lines.
items[].menuItemIdstringrequired: From the menu (a variant's id for items with sizes).
items[].quantityinteger 1–99required: How many.
items[].addOnIdsstring[] (≤ 20): Add-on option ids. Group maximums are enforced.
items[].notestring ≤ 200: e.g. "less spicy" — printed on the KOT.
deliveryobject: Required for DELIVERY: address (5–300), pincode (6 digits), optional landmark, lat, lng.
pickupAtISO-8601 with offset: Optional pickup time.

Request

curl https://api.billzova.com/v1/orders/quote \
  -H "Authorization: Bearer $BILLZOVA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"PICKUP","items":[{"menuItemId":"m-full","quantity":2,"addOnIds":["dip-1"]}]}'

const quote = await fetch('https://api.billzova.com/v1/orders/quote', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.BILLZOVA_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ type: 'PICKUP', items: [{ menuItemId: 'm-full', quantity: 2, addOnIds: ['dip-1'] }] }),
}).then((r) => r.json());

Response

200 · application/json

{
  "object": "quote",
  "currency": "INR",
  "type": "PICKUP",
  "lines": [{
    "menuItemId": "m-full", "name": "Chicken Biryani (Full)", "quantity": 2,
    "unitPrice": { "amount": 33000, "currency": "INR", "display": "₹330" },
    "addOns": [{ "id": "dip-1", "name": "Mint", "price": { "amount": 1000, "currency": "INR", "display": "₹10" } }],
    "note": null, "tax": { "rate": 5, "amount": { "amount": 3300, "currency": "INR", "display": "₹33" } },
    "total": { "amount": 69300, "currency": "INR", "display": "₹693" }
  }],
  "subtotal": { "amount": 66000, "currency": "INR", "display": "₹660" },
  "tax": { "total": { "amount": 3300, "currency": "INR", "display": "₹33" }, "cgst": { "amount": 1650, "currency": "INR", "display": "₹16.5" }, "sgst": { "amount": 1650, "currency": "INR", "display": "₹16.5" } },
  "charges": [],
  "total": { "amount": 69300, "currency": "INR", "display": "₹693" },
  "prepMinutes": 20,
  "quoteId": "9f2c51a0b7e44d1a"
}

Good to know

Never send prices — unknown fields are refused. Billzova always prices from its own menu.

Errors

Code	HTTP	Meaning
VALIDATION_FAILED	422	The body is invalid — `field` says where.
ORDER_TYPE_NOT_ALLOWED	422	Pickup or delivery is not enabled.
OUT_OF_AREA	422	The pincode is outside the delivery area.
BELOW_MINIMUM	422	Below the minimum order amount (`minimum` in the error).
ITEM_NOT_FOUND	422	A menu item does not exist (or belongs to another restaurant).
ITEM_UNAVAILABLE	422	A menu item or add-on is sold out / switched off.
ADDON_INVALID	422	Wrong add-on for the item, a duplicate, or above the group maximum.
SCOPE_MISSING	403	The key is not allowed to do that.
RATE_LIMITED	429	Too many requests — wait for `Retry-After` seconds.