Developer basics
Errors & conventions
A few conventions apply across every endpoint.
Error responses
Errors use standard HTTP status codes with a JSON body:
{
"statusCode": 400,
"message": ["shippingAddress.zipCode must be a string"],
"error": "Bad Request"
}message is a string, or an array of strings for validation errors. Show it to developers, not shoppers.
| Status | Meaning |
|---|---|
| 400 | Invalid input — a missing field, wrong type, or a business rule (out of stock, coupon not valid, no cart). |
| 401 | Missing or expired shopper token, wrong password, or invalid API key. |
| 403 | Authenticated, but not allowed. |
| 404 | The store, product, order or page doesn’t exist (or isn’t published). |
| 5xx | Something went wrong on our side. Safe to retry GETs; for checkout, check the order status before retrying. |
Money
Prices stored on products and orders arrive as decimal strings ("1299.00") so no precision is lost; computed totals may arrive as numbers. Parse both. Razorpay amounts (amount in the checkout response) are in the smallest currency unit — paise for INR.
const price = Number(product.price); // "1299.00" → 1299Dates and IDs
- Timestamps are ISO 8601 strings in UTC.
- IDs are UUID strings. Products, categories, pages and blog posts also have a URL-friendly
slug. - Image URLs are absolute.
Pagination
List endpoints take page (from 1) and limit (default 20, max 100) and return { data, meta: { page, limit, total, totalPages } }.
Rate limits
Sign-in and sign-up codes are limited per email address (a few per 15 minutes); further requests are silently ignored rather than erroring, so don’t retry in a loop. Cache catalog reads where you can — store content changes rarely.
Something unclear or out of date? Tell us