API Versioning
What you'll learn
- How the API is versioned
- Which version to use for each domain
- How to handle version differences
Versioning Strategy
The API uses URL path versioning — the version is embedded in the URL:
/api/v1/products
/api/v2/products/filters
/api/v5/carts
Versions are additive — newer versions add capabilities or change response shapes, but older versions remain available. There is no deprecation timeline for existing versions.
Which Version to Use
| Domain | Recommended Version | Notes |
|---|---|---|
| Authentication | v1 | Login, register, password reset, verification |
| Store | v1 (settings: v2) | GET /api/v1/store for details; GET /api/v2/store/settings for full settings |
| Products — List | v1 | GET /api/v1/products |
| Products — Detail | v2 | GET /api/v2/products/{id} — enriched response with variants |
| Products — Categories | v2 | GET /api/v2/products/categories — richer response |
| Products — Filters | v2 | GET /api/v2/products/filters — richer response |
| Products — Brands | v1 or v2 | Both available |
| Cart | v5 | POST /api/v5/carts — latest cart handling with delivery spec |
| Orders | v4 | POST /api/v4/orders — synchronous order creation, returns the order |
| Orders — async | v5 | POST /api/v5/orders — enqueues submission, returns the cart; poll for the order |
| Deliveries | v3 | POST /api/v3/deliveries/stores — delivery store availability |
| User Profile | v1 | GET /api/v1/users/me |
| Loyalty | v3 | GET /api/v3/users/me/loyalty — latest loyalty response |
| Campaigns | v2 | Richer campaign data |
| Payments | v1 (sources: v2) | GET /api/v2/store/payments/sources for unified source listing |
| Tags | v2 | GET /api/v2/store/tags — enriched tag data |
General Rule
- Use the highest available version for each domain
- When in doubt, check the OpenAPI spec — each endpoint lists the recommended version
Version Differences
Cart: v4 vs v5
v5 is the latest cart version. Both v4 and v5 share the same endpoints, but v5 includes improved validation and delivery specification handling.
| Feature | v4 | v5 |
|---|---|---|
| Create cart | ✅ | ✅ |
| Delivery specification | Separate endpoint | Separate endpoint |
| Item management | ✅ | ✅ |
| Validation | ✅ | ✅ (improved) |
Products: v1 vs v2
| Feature | v1 | v2 |
|---|---|---|
| Product detail | Basic | Enriched (variants, inventory) |
| Categories | Flat list | Hierarchical with metadata |
| Filters | Basic | Dynamic with counts |
| Brands | ✅ | ✅ (same) |
Mixing Versions
It is safe and expected to mix versions across different domains in the same application. For example, a typical storefront uses:
GET /api/v1/store ← v1 for store details
GET /api/v2/products/filters ← v2 for enriched filters
GET /api/v1/products ← v1 for product listing
GET /api/v2/products/{id} ← v2 for product detail
POST /api/v5/carts ← v5 for cart
POST /api/v4/orders ← v4 for checkout
GET /api/v3/users/me/loyalty ← v3 for loyalty
Tip: Click any endpoint in the API Reference tab to see its full documentation, request/response schemas, and code samples.