Versioning & Deprecation

The public API ships under /v1/*. v1 is the only contract currently published. New functionality is added additively; breaking changes will only ever appear in a future major version such as /v2/*.

Additive vs breakingCopy Anchor Link

Treat your client as tolerant of additions. The following are not breaking and can ship at any time on v1:

• A new optional request parameter.
• A new field in a response body.
• A new enum case in an existing enum (subscription status, webhook event, payment provider).
• A new endpoint.
• A new error code (error.code).
• A reworded error.message. The stable contract is error.code, not the free-form message.

The following are breaking and will not happen on v1:

• Removing a field from a response.
• Renaming a field.
• Changing a field's type (e.g. string → integer).
• Adding a new required request parameter.
• Changing the semantics of an existing parameter or enum case.
• Renaming an endpoint path.
• Changing an HTTP status code for an existing scenario.

Webhook payload versioningCopy Anchor Link

Outbound webhook envelopes carry an api_version field. Consumers that care about payload stability should read it and branch on value changes — additive changes leave the version stamp unchanged.

{
  "type": "subscription.created",
  "api_version": "2026-05-01",
  "created_at": "2026-05-18T10:05:00Z",
  "project_id": "prj_...",
  "data": {/* event-specific payload */}
}

Subscribing to a new event type is never breaking — the envelope shape doesn't change, just the type value.

When a breaking change is eventually neededCopy Anchor Link

If Subscriby ever needs to break a contract on the REST API, the process will be:

1. A new major version (/v2/*) is published alongside /v1/*.
2. v1 continues to operate for a long transition window so existing integrations don't break.
3. Affected responses carry Sunset and Deprecation headers per RFC 8594 as the window narrows.
4. After the window closes, v1 is removed and callers receive 410 Gone.

This document will be updated when a v2 contract ships. Today, v1 is the only version.

RelatedCopy Anchor Link

• Error envelope — stable error.code strings.
• OpenAPI specification — machine-readable v1 shape.