API Changelog & Breaking Change Policy

Versioning

The Stackd API is versioned via the URL path: /api/v1/. The current version is v1.

When a breaking change is required, a new version (/api/v2/) will be introduced alongside the existing version. Both versions will run in parallel for a minimum of 6 months before the older version is retired.

---

What constitutes a breaking change

The following are considered breaking changes and will only be introduced in a new major version:

• Removing an endpoint
• Removing or renaming a required request field
• Removing or renaming a response field that is documented in the schema
• Changing the type of a response field (e.g. string → integer)
• Changing authentication requirements for an endpoint
• Reducing or modifying the rate limit in a way that affects current usage
• Changing error response structure (type, status, detail fields of RFC 7807 errors)

---

What is not a breaking change

The following changes can be made to v1 without a version bump:

• Adding new optional request fields
• Adding new response fields (your client should ignore unknown fields)
• Adding new endpoints
• Adding new error detail values for new business rule violations
• Increasing the rate limit
• Performance improvements with no observable behaviour change

---

Non-breaking change policy

Non-breaking changes are deployed without notice to the existing version. Your integration should:

• Ignore unknown JSON fields in API responses (do not use strict schema validation that rejects unknown fields).
• Not depend on the exact set of fields returned — only the fields you use.

---

Deprecation notices

When an endpoint or field is scheduled for removal in a future version:

1. A Deprecation response header will be added to affected responses: Deprecation: true.
2. A Sunset header will indicate the retirement date: Sunset: Sat, 01 Nov 2026 00:00:00 GMT.
3. An email notice will be sent to the owner email address of all tenants with active API tokens.

The minimum deprecation notice period is 90 days before the endpoint or field is removed from the current version.

---

Changelog

v1 — Initial release (2026-05)

Endpoints available at launch:

Method	Path	Description
GET	/api/v1/customers	List customers
GET	/api/v1/customers/{ulid}	Get customer
POST	/api/v1/customers	Create or upsert customer
PATCH	/api/v1/customers/{ulid}	Update customer
GET	/api/v1/customers/{ulid}/transactions	Customer transaction history
GET	/api/v1/transactions/{ulid}	Get transaction
POST	/api/v1/transactions/{ulid}/void	Void transaction
GET	/api/v1/rewards	List active rewards
POST	/api/v1/redemptions	Create redemption
GET	/api/v1/redemptions/{ulid}	Get redemption
POST	/api/v1/redemptions/{ulid}/fulfil	Fulfil redemption
GET	/api/v1/coupons	List coupons
POST	/api/v1/coupons/{ulid}/redeem	Redeem voucher
GET	/api/v1/coupons/{ulid}/redemptions	Coupon redemption history
GET	/api/v1/reports/summary	Transaction summary report
GET	/api/v1/reports/customers/top	Top customers report
GET	/api/v1/reports/coupons	Coupon stats report
GET	/api/v1/tokens	List API tokens
POST	/api/v1/tokens	Create API token
DELETE	/api/v1/tokens/{id}	Revoke API token
GET	/api/v1/platform/tenants	List tenants (super-admin)
POST	/api/v1/platform/tenants	Create tenant (super-admin)
PATCH	/api/v1/platform/tenants/{id}	Update tenant (super-admin)
GET	/api/v1/platform/invoices	List invoices (super-admin)

Token scopes available at launch:

customers:read, customers:write, transactions:write, rewards:read, coupons:read, reports:read

---

Planned additions (not committed, subject to change)

The following capabilities are under consideration for a future v1 minor update or v2:

• POST /api/v1/transactions — PIN-less direct transaction recording (API-only path)
• GET /api/v1/customers/{ulid}/redemptions — redemption history per customer
• Webhook delivery — push events to your endpoint rather than polling
• Customer portal token — scoped read-only access for customer-facing applications

These are not commitments. The changelog will be updated when changes land.

---

Support

For integration questions or to report an API issue: api-support@yourloyalty.app

For breaking change notices and deprecation announcements, ensure the owner email address on your tenant account is current.