# 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*.

<!--
Guidance: How to use this template
- This is the API-level log for developers who call the API. It differs
  from the product-level Changelog (`dev/changelog`), which records all
  user-visible changes of a product release, and from Release Notes
  (`dev/release-notes`), which explain a release to a broader audience.
  Link the three; do not copy entries between them by hand.
- Fill sections 1 to 3 once, when you adopt the log. After that, every
  API change adds one entry in section 5 and, where relevant, a row in
  sections 4, 6 and 8.
- Generate the raw list of changes from the OpenAPI or AsyncAPI diff in
  CI, then have a person classify each change and write the reader-facing
  sentence. A diff tool finds changes; it cannot tell readers what to do.
- Newest entries first. Dates in ISO 8601 (YYYY-MM-DD), times in UTC.
- The worked example is fictional: the Corvid Commerce Orders API.
- Related documents: Deprecation Notice (`docs/deprecation-notice`), API
  Versioning and Deprecation Policy (`architecture/api-deprecation-policy`),
  API Reference (`dev/api-reference`), API Overview (`docs/api-overview`),
  SDK Overview (`docs/sdk-overview`), Migration Guide
  (`docs/migration-guide`), Known Issues (`docs/known-issues`), REST API
  Specification (`architecture/rest-api-specification`).
-->

## Document control

<!-- Guidance: The changelog is a living document. Version the template-level conventions (sections 1 to 3) here; individual entries carry their own dates and IDs. Pitfall: editing a published entry silently; correct it with a dated note instead. -->

| Field | Value |
|---|---|
| Document ID | [APICHG-LOG-001] |
| API | [Orders API] |
| API description format | [OpenAPI 3.2.1 / OpenAPI 3.1.x / AsyncAPI 3.1.0] |
| Description document URL | [https://developer.example.com/openapi/orders.yaml] |
| Current API versions | [v2 (current), v1 (deprecated)] |
| Version | [1.0] |
| Status | [Active] |
| Owner | [@api-product-owner] |
| Approvers/reviewers | [@api-platform-lead], [@developer-relations], [@technical-writer] |
| Last updated | YYYY-MM-DD |
| Classification | Public |
| Feeds | [Atom feed URL], [JSON feed URL] |

### Approvals

| Role | Name | Decision | Date |
|---|---|---|---|
| API product owner | [@name] | [Approve / Reject] | YYYY-MM-DD |
| API platform lead | [@name] | [Decision] | YYYY-MM-DD |
| Technical writer | [@name] | [Decision] | YYYY-MM-DD |

### Revision history

| Version | Date | Author | Change summary |
|---|---|---|---|
| 0.1 | YYYY-MM-DD | [@name] | First draft of conventions |
| 1.0 | YYYY-MM-DD | [@name] | *Example:* Conventions approved; log published with entries from v2.0.0 onward |
| 1.1 | YYYY-MM-DD | [@name] | *Example:* Added the event API section and AsyncAPI diff links |

## Contents

<!-- Guidance: Keep this list aligned with the headings. Section 5 grows over time; keep its anchors stable so that release notes can link to them. -->

1. [Scope and conventions](#1-scope-and-conventions)
2. [Change classification](#2-change-classification)
3. [Entry format](#3-entry-format)
4. [Version index](#4-version-index)
5. [Changelog entries](#5-changelog-entries)
6. [Deprecations and sunsets](#6-deprecations-and-sunsets)
7. [Event API changes](#7-event-api-changes)
8. [SDK compatibility](#8-sdk-compatibility)
9. [Producing the changelog](#9-producing-the-changelog)
10. [Entry review checklist](#10-entry-review-checklist)
11. [Glossary and references](#11-glossary-and-references)

## 1. Scope and conventions

<!-- Guidance: Say exactly what the log covers so that readers trust that an absent entry means no change. Questions: are internal, beta and partner-only operations included? Are documentation-only fixes included? Pitfall: a log that covers "major changes" only, which forces readers to diff the spec themselves. -->

### 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`)).

| Surface | Included | Notes |
|---|---|---|
| *Example:* Generally available operations | Yes | All changes |
| *Example:* Beta operations (marked `x-beta: true`) | Yes | Breaking changes allowed without deprecation; flagged as Beta |
| *Example:* Partner-only operations | No | Partner changelog |
| *Example:* Documentation text corrections | Only when they change the documented contract | Typo fixes are not logged |
| [Surface] | [Yes / No] | [Notes] |

### 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

| Convention | Rule |
|---|---|
| Order | Newest first, grouped by API major version |
| Dates | Release date of the change in production, ISO 8601, UTC |
| Identifiers | `APICHG-NNN`, assigned in order of production date, global across API versions, never reused, never renumbered |
| Operation names | `operationId` plus method and path, for example `listOrdersV2` (`GET /v2/orders`) |
| Event names | AsyncAPI `operationId` (*Example:* `orderUpdated`) together with the event type that webhook payloads carry (*Example:* `order.updated`), and the message name |
| Corrections | Add a dated "Correction" line to the entry; never delete a published entry |
| Language | English; short sentences that start with what changed for the client |

## 2. Change classification

<!-- Guidance: Classify every entry with exactly one class. The class tells the reader how urgently to act. Questions: could a correct, well-behaved client break? Could a client that ignores unknown fields break? Pitfall: calling a behavioural change "additive" because the schema did not change. -->

| Class | Meaning | Client action | Version impact |
|---|---|---|---|
| Additive | New capability that existing clients can ignore: a new operation, an optional parameter, a new response field, a new event type | None required | Minor |
| Behavioural | Same contract shape, but observable behaviour changes: a default, a limit, validation, ordering, timing, an error code for an existing condition | Review; test if you depend on the behaviour | Minor or patch, as the policy decides |
| Breaking | A correct existing client can fail: removal or rename, a new required input, a narrower type, a changed meaning, a removed enum value | Change code before the sunset date | Major, after deprecation |
| Deprecation | Marks an item for future removal; behaviour unchanged until sunset | Plan migration | Minor |
| Security | Change made to fix a vulnerability, possibly breaking, with shortened notice under the policy | Act within the stated window | As required |

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).

```mermaid
flowchart TD
    A[Change detected in diff or design] --> B{Can a correct existing<br/>client fail?}
    B -- Yes --> C{Security fix with<br/>policy exception?}
    C -- Yes --> S[Security]
    C -- No --> K[Breaking: needs new major<br/>version and deprecation first]
    B -- No --> D{Does observable behaviour<br/>change for existing calls?}
    D -- Yes --> V[Behavioural]
    D -- No --> E{Is an item marked<br/>for removal?}
    E -- Yes --> P[Deprecation]
    E -- No --> AD[Additive]
```

### 2.1 Examples by class

| Change | Class | Reason |
|---|---|---|
| *Example:* New optional query parameter `updated_since` on `listOrdersV2` | Additive | Existing calls are unaffected |
| *Example:* New response field `fulfilment_channel` | Additive | Clients must ignore unknown fields (documented in the API overview) |
| *Example:* New enum value `partially_shipped` on `status` | Behavioural | Clients that switch on all known values may fail; the policy treats new enum values as behavioural, not additive |
| *Example:* Default `limit` changes from 50 to 25 | Behavioural | Same contract, different result size |
| *Example:* `Idempotency-Key` becomes required on `createOrderV2` | Breaking | Existing calls without the header fail |
| *Example:* `operationId` `getOrder` renamed `retrieveOrder` | Breaking for generated SDKs | Method names in generated code change, even though HTTP is unchanged |
| [Change] | [Class] | [Reason] |

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

<!-- Guidance: Every entry has the same fields so that readers can scan and tools can parse. Questions: which fields are mandatory for each class? Pitfall: entries that say "various improvements" with no operations named. -->

| Field | Required | Content |
|---|---|---|
| ID | All | `APICHG-NNN` |
| Date | All | Production release date, YYYY-MM-DD |
| API version | All | `info.version` after the change, for example `2.4.0` |
| Class | All | Additive, Behavioural, Breaking, Deprecation or Security, plus Beta or Fix flags |
| Summary | All | One sentence, starting with what the client can now do or must now do |
| Affected operations | All | `operationId` with method and path, or AsyncAPI operation and message |
| Details | Behavioural, Breaking, Security | What changed, before and after, with a short example |
| Action required | Behavioural, Breaking, Deprecation, Security | What the client must do and by when |
| OpenAPI or AsyncAPI diff | All | Link to the diff between the previous and new description documents |
| Deprecation and Sunset | Deprecation, Breaking | Header values exactly as sent, and the human-readable dates |
| SDK versions | All | First SDK release per language that includes the change |
| Links | Optional | Deprecation notice, migration guide, reference page, known issue |

Template for a new entry:

```markdown
#### 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

<!-- Guidance: One row per API version so that readers can see support status at a glance. Update the row whenever a status or date changes. Pitfall: listing only the current version, which hides how long older versions remain supported. -->

| API version | Status | Released | Deprecated | Sunset | Description document | Notes |
|---|---|---|---|---|---|---|
| v2 (2.4.0) *(Example)* | Current | 2026-10-20 | n/a | n/a | `orders-v2.4.0.yaml` | Latest minor |
| v2 (2.0.0) *(Example)* | Current (superseded minor) | 2026-06-01 | n/a | n/a | `orders-v2.0.0.yaml` | Minor versions are cumulative |
| v1 (1.10.0) *(Example)* | Deprecated | 2026-10-26 | 2026-11-02 | 2027-11-17 23:59:59 UTC | `orders-v1.10.0.yaml` | v1.0.0 released 2024-03-04; see Deprecation Notice |
| [vN] | [Current / Deprecated / Sunset / Beta] | YYYY-MM-DD | YYYY-MM-DD | YYYY-MM-DD | [file] | [Notes] |

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

<!-- Guidance: This is the log itself. Write each entry for a developer who reads only this entry. Questions: does the summary say what to do? Is every affected operation named? Is the diff link live? Pitfall: one entry that bundles an additive change and a breaking change; split them so that each has one class. -->

### 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

<!-- Guidance: Keep a register of every open deprecation with the exact header values, so that support, SDK teams and readers check one place. Questions: does each row link to a customer-facing deprecation notice? Has the sunset passed and been confirmed? Pitfall: header values in the code that drift from the published dates. -->

| ID | Item | Deprecated | `Deprecation` value | Sunset | `Sunset` value | Replacement | Notice | Status |
|---|---|---|---|---|---|---|---|---|
| DEP-001 *(Example)* | Orders API v1 (all operations) | 2026-11-02 | `@1793577600` | 2027-11-17 23:59:59 UTC | `Wed, 17 Nov 2027 23:59:59 GMT` | Orders API v2 | [DEP-001 notice] | Announced (headers sent since 2026-10-26) |
| DEP-002 *(Example)* | Query parameter `customer_email` on `listOrdersV2` | 2026-12-01 | `@1796083200` | 2027-12-01 23:59:59 UTC | `Wed, 01 Dec 2027 23:59:59 GMT` | `customer_id` | [DEP-002 notice] | Planned (entry to be logged when the headers ship) |
| [DEP-NNN] | [Item] | YYYY-MM-DD | `@[seconds]` | YYYY-MM-DD HH:MM UTC | `[HTTP-date]` | [Replacement] | [Link] | [Announced / Deprecated / Sunset] |

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

<!-- Guidance: Webhooks and event streams break clients just as HTTP operations do, but consumers often cannot see a header. Log their changes with the same classes and link the AsyncAPI diff. Pitfall: changing a payload in place, which breaks consumers that validate strictly. -->

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

| AsyncAPI element | Additive | Behavioural | Breaking |
|---|---|---|---|
| Channel | New channel | Change in delivery guarantees or ordering | Channel removed or address changed |
| Operation | New operation | Change in retry schedule or batching | Operation removed or action changed |
| Message payload | New optional property | New enum value, changed timing | Property removed, renamed, retyped or made required |
| Message headers | New optional header | Header value format clarified | Header removed or signature scheme changed |

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.

| ID | Date | Event | Class | Summary | AsyncAPI diff | SDK versions |
|---|---|---|---|---|---|---|
| APICHG-015 *(Example)* | 2026-10-26 | `orderUpdated` (`order.updated`) | Deprecation | v1 payload `OrderUpdatedV1` deprecated; delivered until 2027-11-17 23:59:59 UTC | [Diff] | 4.8.0 |
| APICHG-013 *(Example)* | 2026-10-20 | `orderUpdated` (`order.updated`) | Behavioural | New status value `partially_shipped` | [Diff] | 5.3.0 |
| APICHG-011 *(Example)* | 2026-08-11 | `orderRefunded` (`order.refunded`) | Additive | New event on channel `orders.refunds` | [Diff] | 5.1.0 |
| [APICHG-NNN] | YYYY-MM-DD | [Event] | [Class] | [Summary] | [Link] | [Versions] |

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

## 8. SDK compatibility

<!-- Guidance: Tell readers which SDK release first supports each API version and which SDK releases stop working at a sunset. Questions: do SDK major versions follow API major versions? Which SDK releases are end of support? Pitfall: an SDK release that silently changes the default API version. -->

| SDK | API v1 support | API v2 support | Latest | Default API version | End of support |
|---|---|---|---|---|---|
| Python `corvid-commerce` *(Example)* | 4.x | 5.0.0 and later | 5.3.0 | v2 | 4.x on 2027-11-17 |
| TypeScript `@corvid/commerce` *(Example)* | 4.x | 5.0.0 and later | 5.3.0 | v2 | 4.x on 2027-11-17 |
| Java `com.corvid:commerce` *(Example)* | 4.x | 5.0.0 and later | 5.3.0 | v2 | 4.x on 2027-11-17 |
| Go `corvid.example/commerce` *(Example)* | v4 | v5.0.0 and later | v5.3.0 | v2 | v4 on 2027-11-17 |
| [SDK] | [Range] | [Range] | [x.y.z] | [vN] | YYYY-MM-DD |

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

<!-- Guidance: Make the changelog a by-product of the delivery pipeline, with a human writing the reader-facing text. Questions: does CI fail when the description document changes without an entry? Who approves the class of a change? Pitfall: writing entries from memory after the release. -->

```mermaid
sequenceDiagram
    participant Dev as API developer
    participant CI as CI pipeline
    participant TW as Technical writer
    participant Rev as API reviewer
    participant Pub as Docs site and feeds
    Dev->>CI: Pull request changes OpenAPI or AsyncAPI document
    CI->>CI: Lint description, compute diff against last release
    CI-->>Dev: Diff report with suggested class per change
    Dev->>TW: Draft entry (summary, operations, action)
    TW->>Rev: Edited entry with class
    Rev-->>TW: Class confirmed or changed
    Rev->>CI: Approve; breaking change blocked unless policy allows
    CI->>Pub: On release, publish entry, diff link and feeds
```

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

<!-- Guidance: Run this checklist on every entry before publication. Pitfall: an entry whose diff link points to a branch that is later deleted. -->

| ID | Check | Done |
|---|---|---|
| REV-001 | Exactly one class; Beta and Fix flags added where they apply | [ ] |
| REV-002 | Summary starts with what the client can or must do | [ ] |
| REV-003 | Every affected operation named by `operationId`, method and path | [ ] |
| REV-004 | Diff link is permanent (tagged release, not a branch) | [ ] |
| REV-005 | Action and deadline stated for behavioural, breaking, deprecation and security entries | [ ] |
| REV-006 | `Deprecation` and `Sunset` values decode to the stated dates; sunset not before deprecation | [ ] |
| REV-007 | SDK versions listed for each language and actually released | [ ] |
| REV-008 | Version index (section 4) and deprecation register (section 6) updated | [ ] |
| REV-009 | Examples contain fictional data only, no keys or customer data | [ ] |
| REV-010 | Entry appears in the feeds with the same text | [ ] |

## 11. Glossary and references

<!-- Guidance: Keep definitions consistent with the API overview and the deprecation policy. Pitfall: a different meaning of "breaking" in each document. -->

### 11.1 Glossary

| Term | Meaning in this changelog |
|---|---|
| Additive change | A change that existing clients can ignore safely |
| Behavioural change | A change in observable behaviour without a change in contract shape |
| Breaking change | A change that can make a correct existing client fail |
| Deprecation | Marking an item for future removal while it keeps working |
| Sunset | The time after which a deprecated item is expected to stop responding |
| Description document | The OpenAPI or AsyncAPI document that describes the API |
| Diff | Machine-computed list of differences between two description documents |
| `operationId` | Unique identifier of an operation in the description document; drives SDK method names |

### 11.2 References

| Reference | Version or date | Use in this template |
|---|---|---|
| OpenAPI Specification, spec.openapis.org | 3.2.1, 2026-09-10 (Apache License 2.0) | Description document, `operationId`, `deprecated` fields |
| AsyncAPI Specification, asyncapi.com | 3.1.0, 2026-01-31 (Apache License 2.0) | Event API description, channels, operations, messages, schema `deprecated` |
| RFC 9745, The Deprecation HTTP Response Header Field, rfc-editor.org | Standards Track, March 2025 | `Deprecation` header and `deprecation` link relation |
| RFC 8594, The Sunset HTTP Header Field, rfc-editor.org | Informational, May 2019 | `Sunset` header and `sunset` link relation |
| RFC 9651, Structured Field Values for HTTP, rfc-editor.org | Standards Track, September 2024 | Date type used by `Deprecation` |
| Semantic Versioning, semver.org | 2.0.0 | Major, minor and patch meaning |
| RFC 3339, Date and Time on the Internet: Timestamps | July 2002 | Timestamp format in examples |
| [Internal API deprecation policy] | [Version] | Notice periods and exception rules |

## 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.