Our API promise

The Octopus Cards API is the foundation a customer-facing product is built on. To make that worth the investment, Octopus Cards commits to a specific set of guarantees about how the API will — and will not — change over time.

This page is that contract.

What stays the same

Every endpoint runs on /api/v1/. While v1 is the active major version, Octopus Cards commits to four guarantees:

• Fields are never removed from response bodies. If order.discount is documented today, it will exist tomorrow.
• Fields are never renamed. is_user_fixable will not become userFixable. client_reference will not become clientReference.
• Input rules never get stricter. An optional field will not become required. Validation will not be tightened in a way that rejects requests that work today.
• No silent semantic changes. If a field's meaning needs to change, the change ships as a new field — never as a redefinition of an existing one.

That is the whole commitment in one paragraph: anything an integration depends on today keeps working tomorrow.

What can change inside v1

To keep Octopus Cards moving forward without breaking integrations, Octopus Cards reserves the right to make purely additive changes:

• Add optional fields to request bodies.
• Add fields to response bodies.
• Add new endpoints.
• Add new error codes for existing endpoints.
• Add new enum values for existing string-typed enum fields (e.g. a new status_text, a new failure_code).
• Relax validation — accept things that used to be rejected.
• Fix bugs where the documented behaviour didn't match the implementation. In that case the documented behaviour wins.

Additive changes require no action from existing integrations, provided the integration ignores unknown JSON fields and tolerates unknown enum values — API versioning covers the language-by-language patterns.

When v2 happens

If and when Octopus Cards needs to ship a v2, the rollout is governed by these commitments:

1. Both versions run side-by-side. v1 is fully supported for the entire transition — no feature regressions, no new restrictions.

2. Minimum 12-month deprecation window. No early sunsets, no exceptions.

3. Migration guide published before deprecation begins. Field-by-field mapping, behavioural differences, and the recommended migration order.

4. Per-endpoint deprecation headers appear on v1 responses so the sunset date is machine-readable:

   Deprecation: Wed, 15 Oct 2025 00:00:00 GMT
   Sunset: Wed, 15 Oct 2026 00:00:00 GMT
   Link: </docs/migration/v1-to-v2>; rel="deprecation"

5. Email notice to every active integration contact — not just a docs update.

6. 410 Gone after sunset. A clean failure mode — integrations get a sharp signal rather than silent semantic drift.

What this means for an integration

The full integration cost of relying on this promise is small:

• Pin the version in code. /api/v1/ belongs in an SDK-layer constant, not in a runtime config.
• Ignore unknown JSON fields. Most parsers do this by default; a few (Jackson, strict dataclasses) need explicit configuration.
• Treat unknown enum values as "log and fall through" to a safe default — never as a fatal condition.
• Watch the Changelog and Deprecation headers for additive announcements and (rare) breaking-change notices.

Nothing beyond those four habits is required.

Next

• API versioning — defensive-parsing patterns and the language-by-language configuration that makes this promise easy to absorb.
• Changelog — every additive change, every behavioural shift, every breaking change.