Conventions

Money

Every monetary value is an integer count of minor units of its stated currency.

Currency	Minor unit	Human amount	On the wire
INR	paise	₹500.00	`"50000"`
USD	cents	$25.00	`"2500"`
JPY	yen (zero-decimal)	¥1000	`"1000"`

Direction	Accepted types	Validation
In responses	`string`	Always a string. Values can exceed what a double holds exactly, and a string is the only lossless JSON encoding.
In requests	`number` or `string`	A number must be a safe integer (≤ 2⁵³−1) or the request is rejected rather than rounded. A string must match `^[0-9]+$` — no sign, no decimal point, no exponent.

One order carries one currency, a three-letter uppercase ISO 4217 code matching ^[A-Z]{3}$. Lower case is rejected. A mixed-currency order has no single amount to check against and is refused.

Identifiers

Field	Form	Owned by	Constraints
`order_id`	UUID	Endl	Returned by create. Also the pagination cursor for list.
`item_id`	UUID	Endl	Stable per order line.
`voucher_id`	UUID	Endl	Safe to log. Use it as the reference in support tickets.
`canonical_sku`	string	Endl	For example `BIGBASKET--IN--INR`. Stable, and the catalogue cursor.
`partner_order_ref`	string	You	1–200 characters, trimmed, unique across your orders. Your lookup key when a response is lost.
`payment_ref`	string	You	1–200 characters. Recorded against the order, never interpreted or verified.

A malformed identifier answers exactly like an unknown one. Sending not-a-uuid returns 404 ORDER_NOT_FOUND rather than a validation error, so an id-guessing caller learns nothing from the difference.

Error shape

Every error, on every endpoint, has the same two fields.

{ "code": "VALIDATION_ERROR", "message": "items must be a non-empty array" }

Codes are contractual and stable. Messages are written for a human reading a log and may be reworded without notice — never match on them.

Rate limits

Bucket	Sustained	Keyed on	Shares budget with
`/orders*`	300 / min	Your key	All four signed routes
`/orders/{id}/vouchers`	30 / min	Your key	Nothing — its own budget, spent in addition to the group
`/catalog/products`	120 / min	Source IP	Every caller behind that IP

A refusal is 429 RATE_LIMITED with a Retry-After header in whole seconds, never below 1. Honour it — retrying sooner only spends the next window.

Limits are enforced as a token bucket, so a short burst above the sustained rate is admitted. That burst allowance is not contractual and should not be designed against.

Size limits

Limit	Value	Exceeding it returns
Request body	1 MiB	`413`
Items per order	1–50	`VALIDATION_ERROR`
Units per item (`qty`)	1–1000	`QUANTITY_LIMIT_EXCEEDED`
String fields	1–200 chars	`VALIDATION_ERROR`

Pagination

Endpoint	Cursor is	Default	Max	End of pages
`/catalog/products`	`canonical_sku`	100	500	`next_cursor` is `null`
`/orders`	`order_id`	25	100	A page shorter than `limit`

limit is clamped rather than rejected: a value above the maximum silently becomes the maximum, and a non-numeric value becomes the default.

The two endpoints end differently. The catalogue gives you a next_cursor that goes null. GET /orders returns no cursor field at all — continue from the order_id of the last order in the page, and stop when a page comes back shorter than limit.

Introduction

Endpoints

Money

Identifiers

Error shape

Rate limits

Size limits

​Money

​Identifiers

​Error shape

​Rate limits

​Size limits

​Pagination

Money

Identifiers

Error shape

Rate limits

Size limits

Pagination