Versioning Strategy

We are updating our API versioning strategy to support the growing needs of the Lightspeed Retail (X-Series) platform. We are moving away from Semantic Versioning (e.g., v0.9, v2.0, v2.1, v3.0) to a Date-Based Versioning strategy.

This change ensures a more predictable release schedule and provides a unified experience where every version contains the full set of APIs.

Date-Based Versioning

Each new API version is identified by its release date in the format YYYY-MM.

Example:

• 2026-01
• 2026-04

The version is specified in the URL path:

GET /api/2026-01/products

Why the Change?

• Predictability: You know exactly when new versions are released and how long they are supported.
• Unified Access: unlike our previous semantic versions where features might be split, each date-based version includes the full set of APIs. Your application only needs to reference a single version to access all capabilities.
• Simplicity: The version number communicates the age and recency of the API immediately.

Release Schedule

We publish a new API release every 3 months (Quarterly).

Support Lifecycle

Each version is supported for a minimum of 12 months. This gives you a clear window to plan, test, and migrate your integrations.

Example Timeline:

We recommend reviewing your integration at least once a year to upgrade to a supported version. However, we encourage regular reviews of our changelog to take advantage of new features and improvements as they're released.

Legacy Behavior & Fallbacks

If you make a request to a version that is no longer supported (has reached End-Of-Life), your request will automatically be served by the oldest currently supported version.

For example, if 2026-01 is no longer supported, requests to it might be handled by 2026-04 (if that is the oldest supported version). This fallback mechanism prevents immediate breakage, but we strongly advise keeping your integration updated to avoid unexpected behavior changes.

Beta Releases

To help you prepare for upcoming changes, the next scheduled release is available in a Beta state before its official launch.

This allows you to test your integration against the upcoming version in advance. The version will remain in Beta status until its official release date arrives.

Note: Beta versions may receive updates or breaking changes before they are finalized. We recommend using them for testing and development, not for production critical workflows until they are officially released.