Skip to main content

​
Why versioning exists

Loop’s API is used by merchants and third-party developers to build integrations. Without versioning, every change Loop makes could break existing code. With versioning, you pin your integration to a specific API version and it continues to behave exactly as you built it — regardless of changes made to newer versions.

​
Version format

Loop uses a date-based version format: YYYY-MM. Loop ships new versions on a regular, predictable release schedule, so the version lifecycle windows below stay consistent and easy to plan around. Each version is named after the month it ships (YYYY-MM), and a new version is cut whenever there are meaningful breaking changes to release. The version appears directly in the URL path:
Each new version is preceded by a 2-week code freeze, during which no additional breaking changes are accepted into the release. This gives the team time to finalise documentation and notify developers before the version ships.
The alias v1 is a legacy convenience alias for version 2026-07. It exists purely for backward compatibility — new integrations should specify 2026-07 (or a later version) explicitly rather than relying on v1. Once 2026-07 reaches the Sunset stage of its lifecycle, the v1 alias will be phased out entirely and requests must use an explicit YYYY-MM version.

​
Specifying your version

Include the version in every request URL. For example:
If you omit the version from the URL, the API defaults to the oldest currently supported version. This is not recommended for production integrations — always specify a version explicitly so your integration’s behaviour is predictable.

​
Version lifecycle

Each version moves through three stages:
Lifecycle timing: a version is deprecated 12 months after its release date and sunset 15 months after its release date.Example: a version released in a given month enters the Deprecated stage 12 months later, and is Sunset 3 months after that (15 months after release).
When your version is deprecated, watch for the Sunset response header — it tells you the exact date your version will be retired so you can plan your migration.

​
Breaking vs. non-breaking changes

Not all API changes require a new version. Loop distinguishes between breaking and non-breaking changes:

​
Breaking changes — shipped in a new version

A change is breaking if existing code would stop working without the developer doing anything. The following are always breaking changes:
  • Removing or renaming a field in a response
  • Changing a field’s data type
  • Making a previously optional request parameter required
  • Removing an endpoint
  • Changing the structure of error responses
  • Removing a value from an enum

​
Non-breaking changes — shipped to all versions

The following are non-breaking and are added to all supported versions simultaneously:
  • Adding new optional fields to responses
  • Adding new optional request parameters
  • Adding new endpoints
  • Adding new webhook event types
The rule of thumb: if your existing code would break without you touching it, it’s a breaking change and will only appear in a new version.

​
How backward compatibility works

Loop’s API runs the latest internal logic on every request. When you use an older version, response transformation functions reshape the output to match the schema that version defined. This means:
  • You’re always running on the most up-to-date infrastructure and business logic
  • Bug fixes are applied across all supported versions automatically — you get improvements without needing to upgrade
  • Your integration sees the world through the lens of the version you chose

​
Unstable version

The unstable version is a preview of the next planned release:
Do not use unstable in production. The unstable version may change at any time without notice. It exists to let you explore upcoming changes and provide feedback before they are locked in.All responses from the unstable version include an X-Loop-API-Warning header to remind you that the version is not production-ready. Webhooks cannot be configured to use the unstable version.

​
Webhooks

Webhooks use the same versioning system as the REST API. Your webhook version is set once at the shop level and applies to all webhook payloads your shop receives. Webhook version is not configured through the API. Instead, set it on the outgoing webhook configuration page in the Loop admin portal, where you can select which API version your webhook payloads should be shaped by. The same version lifecycle — Active, Deprecated, Sunset — applies to webhook versions. When a new API version introduces a breaking change, it can affect both REST API responses and webhook payloads. Plan migrations for both surfaces together.
Webhooks cannot be pinned to the unstable version.

​
Quick reference