Skip to content

API versioning & deprecation

The /api/v1 prefix is litecommerce's stable API boundary. We make additive changes inside that version by default. When an external integration would need to change to keep working, we treat the change as breaking and give it an explicit deprecation lifecycle.

This policy applies to operations and schemas published in the API reference for merchant, storefront, and customer integrations. It does not turn internal platform routes or inbound provider callbacks into supported tenant integration surfaces.

Compatibility contract

An additive change can ship within /api/v1 without a new version or deprecation window. Examples include:

  • a new operation;
  • a new optional request field or header;
  • a new response field when the published response object does not declare additionalProperties: false;
  • a new error code that keeps the documented HTTP status and error envelope semantics; or
  • a documentation clarification that does not change runtime behavior.

A change is breaking when a conforming integration must change to preserve its current behavior. That includes:

  • removing or renaming an operation, parameter, field, or supported enum value;
  • making an optional input required, or narrowing an accepted input;
  • changing a type, format, unit, meaning, default, or nullability;
  • adding a field to a response object that declares additionalProperties: false, or adding a value to a response enum that is not documented as open-ended;
  • removing, renaming, reusing, or incompatibly changing a documented error code;
  • changing required authentication, permission, or tenant context;
  • changing success, error, pagination, ordering, or idempotency semantics in a way that invalidates the documented client flow; or
  • materially lowering a documented limit for existing integrations.

A response object is open unless its published schema declares additionalProperties: false. Clients must ignore unknown fields on an open response object; adding a field to an explicitly closed object uses the breaking-change lifecycle. Response enums are closed unless the reference documents them as open-ended.

The public error-code catalog is intentionally open-ended. Clients can branch on a known stable code, but must fall back to the HTTP status and generic error envelope behavior for an unknown code. Adding a code is additive only when it preserves those documented semantics. A known code's spelling and meaning remain stable.

If a runtime behavior and the published contract disagree, we normally restore the documented behavior. When integrations could reasonably rely on the long-running behavior instead, we use the breaking-change lifecycle rather than calling the change a bug fix.

Support and notice windows

When a successor stable major version becomes generally available, the prior major version remains supported for at least 12 months. Supported means its documented operations remain available and continue to receive compatibility, security, and critical reliability fixes; it does not promise new features.

Before we remove or incompatibly change a published operation, field, or behavior, we give at least 180 calendar days of notice. A longer date wins: if a major-version support window or an already-announced sunset date extends beyond those 180 days, the surface remains available through the later date.

Deprecation is not removal. A deprecated surface stays supported until its published sunset, and a replacement must be available early enough for an integration to migrate and verify against Preview before the old surface is removed from Production.

Deprecation record

Each breaking change gets one durable record with:

  • the affected operations, fields, or behaviors;
  • why the change is needed;
  • the supported replacement and a migration example;
  • the announcement date;
  • the earliest Production removal date; and
  • any Preview and Production rollout details an integrator needs to verify the migration.

The affected OpenAPI operation or schema is marked deprecated: true where OpenAPI can represent it. The record—not the pull request that introduced the replacement—owns the compatibility clock. A later code change may extend a sunset, but it cannot silently move an active deadline earlier.

Where we announce changes

We publish every deprecation in all of these places:

  1. the API reference, beside the affected contract;
  2. the public litecommerce changelog; and
  3. the tenant communications channel as an API deprecation notice, visible in merchant admin and delivered to organization owners.

When we know a specific integration needs extra coordination, direct outreach may supplement those records, but it does not replace them. The announcement includes the replacement and exact dates, so integrators never have to infer a deadline from a merge, deploy, or schema digest.

Emergency exception

We may shorten the normal notice period only when keeping the old behavior available would create an urgent security or data-safety exposure, violate a legal requirement, or depend on an upstream capability that is no longer available. We limit the change to the smallest affected surface, announce it as soon as it is safe and practical, provide a mitigation or replacement when one exists, and publish the reason the normal window could not be honored.

Policy changes

This page is the durable contract; it is not rewritten for every pull request. New deprecations add records to the reference, changelog, and tenant notice channel under this policy. If the policy itself changes, we announce that change through the same public channels, and it does not shorten a window that has already started.

Related