API Changelog Template (OpenAPI 3.2, AsyncAPI 3.1)

API Changelog: [API name]

Dated, per-version record of every change to a public API that a client developer might notice. Each entry is classified as additive, behavioural or breaking, names the affected operations or channels, links to the OpenAPI or AsyncAPI diff, gives the Deprecation and Sunset header values where they apply, and lists the SDK versions that include the change. It follows the OpenAPI Specification 3.2.1 (3.1.x also widely used) for HTTP APIs, the AsyncAPI Specification 3.1.0 for event APIs, RFC 9745 (Deprecation header, March 2025) and RFC 8594 (Sunset header, May 2019), with Semantic Versioning 2.0.0 for version numbers. Replace every [bracketed] value and every row marked Example.

Document control

Approvals

Revision history

Contents

1. Scope and conventions
2. Change classification
3. Entry format
4. Version index
5. Changelog entries
6. Deprecations and sunsets
7. Event API changes
8. SDK compatibility
9. Producing the changelog
10. Entry review checklist
11. Glossary and references

1. Scope and conventions

1.1 What this log covers

This log records every change to the public contract of [API name] that a client could observe:

• operations, paths, methods, parameters, headers, request and response bodies, status codes and error codes described in the OpenAPI document;
• channels, operations and message payloads described in the AsyncAPI document, for webhooks and event streams;
• authentication, scopes, rate limits, pagination and idempotency rules;
• documented behaviour that is not visible in the schema, such as default sort order, validation rules or timing of asynchronous processing;
• deprecations and sunsets, with their header values.

It does not record internal refactoring, performance work that does not change documented limits, or changes to the dashboard (see the product Changelog (dev/changelog)).

1.2 Versioning scheme

Example: The API has a major version in the path (/v1, /v2). Within a major version, the OpenAPI document carries a Semantic Versioning 2.0.0 number in info.version. A minor version adds backward compatible functionality or marks something as deprecated; a patch version fixes behaviour without changing the contract. Breaking changes require a new major version, except for security fixes under the policy.

Describe your own scheme here. If you use date-based versions or a version header, say how a client selects a version and how long each version is supported. The rules themselves live in Versioning and Release Policy (dev/versioning-release-policy) and API Versioning and Deprecation Policy (architecture/api-deprecation-policy).

1.3 Conventions

2. Change classification

Two supporting flags can be added to any class: Beta (the item is not covered by the compatibility guarantee) and Fix (the change restores documented behaviour).

2.1 Examples by class

Decide in your policy how to treat new enum values and new error codes, and write the decision in the API overview, because readers need to know whether to code defensively. Classify renames of operationId and schema names as breaking for SDK users even when the wire format is unchanged.

3. Entry format

Template for a new entry:

#### APICHG-NNN: [Summary sentence]

- **Date:** YYYY-MM-DD
- **API version:** [x.y.z]
- **Class:** [Additive / Behavioural / Breaking / Deprecation / Security] [Beta] [Fix]
- **Affected operations:** `[operationId]` (`[METHOD] [/path]`)
- **Details:** [Before and after]
- **Action required:** [None / What to do by YYYY-MM-DD]
- **Diff:** [link to OpenAPI or AsyncAPI diff]
- **Deprecation / Sunset:** [`Deprecation: @NNNNNNNNNN`, `Sunset: Day, DD Mon YYYY HH:MM:SS GMT`, or n/a]
- **SDK versions:** [Python x.y.z, TypeScript x.y.z, Java x.y.z, Go x.y.z]
- **Links:** [Reference], [Migration guide], [Deprecation notice]

4. Version index

Keep the description document for every published version available at a stable URL, including sunset versions, so that readers can compare versions and reproduce old behaviour while they migrate.

5. Changelog entries

5.1 Version 2

APICHG-014: Filter orders by last update time (Example)

• Date: 2026-10-20
• API version: 2.4.0
• Class: Additive
• Affected operations: listOrdersV2 (GET /v2/orders)
• Details: New optional query parameter updated_since (RFC 3339 timestamp). When present, only orders updated at or after the given time are returned, in ascending update order.
• Action required: None. Useful for incremental synchronisation instead of full listing.
• Diff: [OpenAPI diff 2.3.0 to 2.4.0]
• Deprecation / Sunset: n/a
• SDK versions: Python 5.3.0, TypeScript 5.3.0, Java 5.3.0, Go 5.3.0

APICHG-013: New order status partially_shipped (Example)

• Date: 2026-10-20
• API version: 2.4.0
• Class: Behavioural
• Affected operations: listOrdersV2, retrieveOrderV2; event orderUpdated
• Details: Orders with some, but not all, lines shipped now report partially_shipped instead of paid. Previously these orders stayed paid until every line shipped.
• Action required: If your code branches on status, add the new value or make sure unknown values fall through to a safe default. Test before 2026-11-03, when the first live orders can enter this status.
• Diff: [OpenAPI diff 2.3.0 to 2.4.0], [AsyncAPI diff 2.3.0 to 2.4.0]
• Deprecation / Sunset: n/a
• SDK versions: Python 5.3.0, TypeScript 5.3.0, Java 5.3.0, Go 5.3.0 (enum updated; older SDKs return the raw string)

APICHG-012: Error code for duplicate idempotency key (Example)

• Date: 2026-09-14
• API version: 2.3.1
• Class: Behavioural, Fix
• Affected operations: createOrderV2 (POST /v2/orders)
• Details: A reused Idempotency-Key with a different request body now returns 422 with code idempotency_key_mismatch, as documented. Before this fix it returned 409 with code conflict.
• Action required: If you handled 409 for this case, also handle 422 with the documented code.
• Diff: No schema change; behaviour now matches the 2.0.0 description
• Deprecation / Sunset: n/a
• SDK versions: Python 5.2.1, TypeScript 5.2.1, Java 5.2.1, Go 5.2.1

APICHG-011: New event orderRefunded (Example)

• Date: 2026-08-11
• API version: 2.2.0
• Class: Additive
• Affected operations: AsyncAPI operation orderRefunded on channel orders.refunds, event type order.refunded
• Details: A new event is sent when a full or partial refund is recorded. Endpoints receive it only after they subscribe to it.
• Action required: None. Subscribe if you reconcile refunds.
• Diff: [AsyncAPI diff 2.1.0 to 2.2.0]
• Deprecation / Sunset: n/a
• SDK versions: Python 5.1.0, TypeScript 5.1.0, Java 5.1.0, Go 5.1.0

APICHG-010: Orders API v2 generally available (Example)

• Date: 2026-06-01
• API version: 2.0.0
• Class: Breaking (new major version)
• Affected operations: All Orders API operations, now under /v2/orders
• Details: Cursor pagination, money as decimal string with currency, required Idempotency-Key on create, new status value cancelled. v1 continues to run unchanged.
• Action required: Migrate before the v1 sunset; see APICHG-015 in section 5.2 and the Migration Guide (docs/migration-guide).
• Diff: [OpenAPI diff 1.9.2 to 2.0.0]
• Deprecation / Sunset: n/a for v2
• SDK versions: Python 5.0.0, TypeScript 5.0.0, Java 5.0.0, Go 5.0.0

5.2 Version 1

APICHG-015: Orders API v1 deprecation announced (Example)

• Date: 2026-10-26 (deprecation takes effect 2026-11-02)
• API version: 1.10.0
• Class: Deprecation (breaking at sunset)
• Affected operations: All operations under /v1/orders; event payload OrderUpdatedV1
• Details: Every /v1/orders response now carries the headers below; until 2026-11-02 the Deprecation value is a future date. From 2026-11-02, accounts with no v1 traffic in the previous 90 days cannot start calling v1. Behaviour is otherwise unchanged until the sunset time, apart from two announced brownouts (2027-09-28 and 2027-10-26).
• Action required: Move to v2 before 2027-11-17 23:59:59 UTC.
• Diff: [OpenAPI diff 1.9.2 to 1.10.0] (adds deprecated: true)
• Deprecation / Sunset: Deprecation: @1793577600, Sunset: Wed, 17 Nov 2027 23:59:59 GMT
• SDK versions: Python 4.8.0, TypeScript 4.8.0, Java 4.8.0, Go 4.8.0 (log a deprecation warning)
• Links: [Deprecation notice], [Migration guide]

Entry numbers are global across versions and increase with date, so APICHG-015 is newer than APICHG-014 even though it appears under version

1. Readers who follow the feed see entries in date order.

6. Deprecations and sunsets

How to read and write the header values:

• Deprecation (RFC 9745) takes a structured-field Date (RFC 9651): @ followed by whole seconds since 1970-01-01T00:00:00Z. Compute it from the deprecation time in UTC and check it by decoding it again.
• Sunset (RFC 8594) takes an HTTP-date in GMT. RFC 9745 requires that the sunset time is not earlier than the deprecation time.
• Send Link headers with rel="deprecation" to the deprecation notice and rel="sunset" to the sunset policy or notice.
• Both headers apply to the resource that returned them unless your documentation states a wider scope.

For the customer-facing announcement of each row, use the Deprecation Notice (docs/deprecation-notice) template.

7. Event API changes

Event changes follow the same classes as section 2, applied to AsyncAPI 3.1.0 objects:

Mark a deprecated payload schema with deprecated: true in the AsyncAPI Schema Object and record the sunset date in the entry, because consumers of an event do not receive HTTP response headers. Offer a version selector per webhook endpoint (Example: api_version on the endpoint configuration) so that consumers switch payload versions when they are ready.

For delivery behaviour, signing and retries, see the Webhook Delivery system design (system-design/design-webhook-delivery).

8. SDK compatibility

Each SDK publishes its own release notes; this table shows only how SDK versions map to API versions. The SDK landing page is the SDK Overview (docs/sdk-overview).

9. Producing the changelog

1. Diff in CI. On every pull request that changes a description document, compute the diff against the last released version with an OpenAPI or AsyncAPI diff tool. Store the diff report as a build artefact and publish it with the release so that the entry can link to it.
2. Gate breaking changes. Fail the build when the diff contains a breaking change on a generally available operation and no approved deprecation exists for it.
3. Draft with the change. The developer drafts the entry in the same pull request. The writer edits for clarity; the API reviewer confirms the class.
4. Publish on release. Publish entries when the change reaches production, not when it merges. Use the production date in the entry.
5. Feeds. Offer an Atom or RSS feed and a JSON file of entries so that readers can subscribe or automate checks. The feed carries the same text as the page.
6. Link outward. Link the entry from the API reference page of each affected operation, from the release notes, and from the deprecation notice where one exists.

Measure the changelog with aggregate page views and feed subscriber counts only. Use cookieless, consent-respecting analytics, honour Global Privacy Control, and never require readers to sign in or give personal data to read or subscribe.

10. Entry review checklist

11. Glossary and references

11.1 Glossary

11.2 References

Standard and licence note

Based on the OpenAPI Specification 3.2.1 (OpenAPI Initiative, https://spec.openapis.org/oas/v3.2.1.html) and the AsyncAPI Specification 3.1.0 (AsyncAPI Initiative, https://www.asyncapi.com/docs/reference/specification/v3.1.0), both published under the Apache License 2.0, on IETF RFC 9745 and RFC 8594 for deprecation and sunset signalling, and on Semantic Versioning 2.0.0. The change classes, entry fields and workflow are original to this template, and no specification text is reproduced. Corvid Commerce and all example entries, versions and values are fictional. This template is original text written for this collection. Check the current specification versions and RFC status before use. Template licence: MIT.