Skip to content
Billzova Developers

Concepts

Versioning & compatibility

What will never change under you in v1, what may be added, and what your code must handle so it keeps working for years.

A restaurant website built today should still work years from now without changes. This page is our promise, and the few rules your code follows so we can keep it.

What we promise in v1

  • We never remove or rename a field, an endpoint, a parameter or an error code.
  • We never change the type or meaning of a field (an amount stays integer paise; a status keeps its meaning).
  • We never make an optional request field required.
  • A breaking change only ever ships as a new major version (/v2), with at least 12 months of overlap and notice to every key owner.

What may be added at any time

  • New endpoints, new optional request fields and new query parameters.
  • New fields in responses, including inside nested objects.
  • New values in lists of enums (for example a new order status or a new error code).
  • New entries in charges (packing, delivery) — they are already part of total.
  • New response headers.

Rules your code follows

  1. Ignore fields you do not know

    Parse the fields you use and ignore the rest. Never fail because a response has an extra field.

  2. Handle unknown enum values

    Treat an unknown status as “in progress” and show the order; treat an unknown error code by its HTTP status (4xx = fix the request, 5xx = retry later).

  3. Show our totals, never add them up

    Display total from the quote or order. Do not compute it from lines, tax or charges — new charge types may appear.

  4. Branch on error codes, not messages

    Messages are for people and may be reworded. error.code never changes.

  5. Retry safely

    Reuse the same Idempotency-Key when you retry a create. A 409 IDEMPOTENCY_IN_PROGRESS means the first try is still running — wait a second and retry.

API versions

Inside v1, behaviour is pinned by a date version. Your key is pinned to the version that was current when it was created, and every response says which one it used in the Billzova-Version header. To try a newer version for one request, send Billzova-Version: <date>; nothing changes for your other calls until you choose to.

VersionNotes
2026-10-17First version of v1.
Ask for a version explicitly
curl https://api.billzova.com/v1/restaurant \
  -H "Authorization: Bearer $BILLZOVA_KEY" \
  -H "Billzova-Version: 2026-10-17"

Money, time and IDs

  • Money is always an object: { "amount": 24900, "currency": "INR", "display": "₹249" } — amount is integer paise.
  • Timestamps are ISO 8601 in UTC (2026-10-24T13:05:00.000Z). Booking date and time are local restaurant time; the restaurant object says "timezone": "Asia/Kolkata".
  • IDs are opaque strings. Store them as text and never parse them. Test-mode IDs start with test_.
  • Every object has object (its type) and test (true for test mode).