# Deprecation Notice: [Feature, endpoint or API version]

> Customer-facing announcement that a product capability, API version,
> endpoint, field or SDK is deprecated and will be retired on a stated
> sunset date. It tells readers what is changing, whether they are
> affected, the dates, the replacement, the migration steps and how to
> find their own usage, and it ships in three variants: a documentation
> page, an email and a changelog entry. The machine-readable signals
> follow RFC 9745 (The Deprecation HTTP Response Header Field, Standards
> Track, March 2025) and RFC 8594 (The Sunset HTTP Header Field,
> Informational, May 2019), with OpenAPI 3.2.1 and AsyncAPI 3.1.0
> deprecation flags. Replace every `[bracketed]` value and every row
> marked *Example*.

<!--
Guidance: How to use this template
- This is the public notice for one deprecation. The internal rules
  that decide notice periods, approval and exceptions live in API
  Versioning and Deprecation Policy (`architecture/api-deprecation-policy`).
  Do not restate the policy here; link to it and apply it.
- Fill section 1 (Notice summary) first and get it approved. Every other
  section, the email and the changelog entry are derived from it, so a
  date changed in section 1 must be changed everywhere in the same edit.
- Write for the person who has to do the migration: a developer, an
  administrator or an integration owner who did not ask for this change.
  Lead with the date and the action, not with the reasons.
- Keep the page at a stable URL for at least the life of the sunset plus
  [12] months. The `Link` headers in section 8 point to it.
- The worked example throughout is fictional: Corvid Commerce retires
  version 1 of its Orders API in favour of version 2.
- Related documents: Migration Guide (`docs/migration-guide`), API
  Changelog (`docs/api-changelog`), Release Notes (`dev/release-notes`),
  Known Issues (`docs/known-issues`), API Overview (`docs/api-overview`),
  SDK Overview (`docs/sdk-overview`), Versioning and Release Policy
  (`dev/versioning-release-policy`).
-->

## Document control

<!-- Guidance: Record who owns the notice and which deprecation record it implements. The notice is a controlled document: once published, dates change only through a new version with a revision history row, and customers are told about the change. -->

| Field | Value |
|---|---|
| Document ID | [DEP-NNN] |
| Deprecated item | [Orders API v1] |
| Replacement | [Orders API v2] |
| Deprecation date | [YYYY-MM-DD] |
| Sunset date | [YYYY-MM-DD HH:MM UTC] |
| Policy applied | [API Versioning and Deprecation Policy, version X.Y] |
| Version | [1.0] |
| Status | [Draft / Approved / Published / Extended / Sunset complete / Withdrawn] |
| Owner | [@api-product-owner] |
| Approvers/reviewers | [@engineering-lead], [@developer-relations], [@support-lead], [@legal-or-commercial] |
| Last updated | YYYY-MM-DD |
| Classification | Public |
| Canonical URL | [https://developer.example.com/deprecations/orders-v1] |
| Internal tracking | [Ticket or epic ID] |

### Approvals

| Role | Name | Decision | Date |
|---|---|---|---|
| API product owner | [@name] | [Approve / Approve with conditions / Reject] | YYYY-MM-DD |
| Engineering lead | [@name] | [Decision] | YYYY-MM-DD |
| Customer support lead | [@name] | [Decision] | YYYY-MM-DD |
| Commercial or legal reviewer (contract terms) | [@name] | [Decision] | YYYY-MM-DD |

### Revision history

| Version | Date | Author | Change summary |
|---|---|---|---|
| 0.1 | YYYY-MM-DD | [@name] | First draft |
| 1.0 | YYYY-MM-DD | [@name] | *Example:* Published with deprecation date 2026-11-02 and sunset date 2027-11-17 |
| 1.1 | YYYY-MM-DD | [@name] | *Example:* Added brownout schedule and the usage report download |

## Contents

<!-- Guidance: Keep this list aligned with the headings. Readers jump straight to sections 4, 6 and 7, so keep those anchors stable once published. -->

1. [Notice summary](#1-notice-summary)
2. [What is changing](#2-what-is-changing)
3. [Who is affected](#3-who-is-affected)
4. [Timeline](#4-timeline)
5. [Replacement and feature mapping](#5-replacement-and-feature-mapping)
6. [Migration steps](#6-migration-steps)
7. [How to detect usage](#7-how-to-detect-usage)
8. [Machine-readable signals](#8-machine-readable-signals)
9. [What happens at sunset](#9-what-happens-at-sunset)
10. [Support and extensions](#10-support-and-extensions)
11. [Announcement variants](#11-announcement-variants)
12. [Frequently asked questions](#12-frequently-asked-questions)
13. [Pre-publication checklist](#13-pre-publication-checklist)
14. [Glossary and references](#14-glossary-and-references)

## 1. Notice summary

<!-- Guidance: This box is what most readers will read. It must answer, in under a minute: what, when, what instead, what do I do. Questions: is the sunset date a calendar date with a time and a time zone? Is there exactly one replacement, or a choice? Pitfall: a summary that explains the history and strategy before it gives the date. -->

| Item | Value |
|---|---|
| What is deprecated | *Example:* Orders API version 1 (all operations under `/v1/orders`) |
| Deprecation date | *Example:* 2026-11-02 (no new features; fixes for security and severe defects only) |
| Sunset date | *Example:* 2027-11-17 23:59:59 UTC, a Wednesday (requests fail after this time) |
| Replacement | *Example:* Orders API version 2 (`/v2/orders`) |
| Action required | *Example:* Move every integration to `/v2/orders` and upgrade the official SDK to version 5.0.0 or later before the sunset date |
| Who must act | *Example:* Any account that called `/v1/orders` in the last 90 days |
| Effort estimate | *Example:* Most integrations need a change to two request fields and one response field; allow one to three days including testing |
| Migration guide | [Link to the migration guide] |
| Where to get help | [Support channel, forum or account manager] |

**Summary in one sentence** (reuse in the email subject and the changelog
title): *Example:* Orders API v1 is deprecated on 2 November 2026 and will
stop working on 17 November 2027; move to Orders API v2 before then.

## 2. What is changing

<!-- Guidance: Name precisely what is deprecated and what is not. List operations, fields, events, SDK methods or UI features by their exact identifiers so readers can search their code. Pitfall: "the legacy endpoints" without a list. -->

State the scope in plain terms and then list every deprecated item. If
only part of an API is deprecated, list what stays as well, because
readers will otherwise assume the worst and migrate more than they need.

### 2.1 Deprecated items

| ID | Type | Identifier | Replacement | Notes |
|---|---|---|---|---|
| DEP-ITEM-001 *(Example)* | Operation | `GET /v1/orders` (`listOrders`) | `GET /v2/orders` (`listOrdersV2`) | Cursor pagination replaces page numbers |
| DEP-ITEM-002 *(Example)* | Operation | `POST /v1/orders` (`createOrder`) | `POST /v2/orders` (`createOrderV2`) | `Idempotency-Key` header becomes required |
| DEP-ITEM-003 *(Example)* | Field | `order.total` (float) | `order.total_amount` (object with `value` string and `currency`) | Removes rounding errors on large amounts |
| DEP-ITEM-004 *(Example)* | Event | `order.updated` v1 payload | `order.updated` v2 payload | Delivered to webhook endpoints that opt in to v2 |
| DEP-ITEM-005 *(Example)* | SDK method | `client.orders.list(page=...)` in SDK 4.x | `client.orders.list()` iterator in SDK 5.x | SDK 4.x reaches end of support on the sunset date |
| [DEP-ITEM-NNN] | [Type] | [Identifier] | [Replacement] | [Notes] |

### 2.2 Not affected

| Item | Status |
|---|---|
| *Example:* Orders API v2, Payments API, Catalogue API | Unchanged |
| *Example:* Order data stored in your account | Unchanged; v2 reads the same orders, no data migration is needed |
| *Example:* Dashboard order screens | Unchanged |
| [Item] | [Status] |

### 2.3 Why we are making this change

Keep this to one short paragraph that names the customer benefit. Readers
accept a deprecation more readily when they can see what they gain, but
the reason must never be longer than the instructions.

*Example:* Version 2 represents money as an exact decimal string with a
currency code, uses cursor pagination that stays consistent while orders
are created, and makes order creation safe to retry. Running two versions
side by side has slowed delivery of new order features, which will ship
on version 2 only.

## 3. Who is affected

<!-- Guidance: Help each reader decide in seconds whether this applies to them. Questions: which account types, plans, regions, SDK versions or integrations are in scope? Can a reader be affected without knowing it (a partner app, a plug-in, a no-code connector)? Pitfall: telling everyone they are affected, which trains readers to ignore notices. -->

You are affected if any of the following is true. Section 7 explains how
to check each one.

| ID | Condition | How to confirm |
|---|---|---|
| AFF-001 *(Example)* | Your code or an integration you run calls any `/v1/orders` operation | Usage report in section 7.1, or `Deprecation` header in your logs |
| AFF-002 *(Example)* | You use an official SDK at version 4.x or earlier | Check your dependency lock file |
| AFF-003 *(Example)* | Your webhook endpoint receives `order.updated` with `"api_version": "1"` | Webhook delivery log in the dashboard |
| AFF-004 *(Example)* | You use a third-party app or connector that reads orders | Ask the vendor; the partner list in section 10 shows who has already migrated |
| [AFF-NNN] | [Condition] | [Check] |

You are **not** affected if you use only the dashboard, only Orders API
v2, or an official SDK at version 5.0.0 or later with default settings.

If you build software that other people install (an app, a plug-in, a
connector), you are responsible for updating it and for telling your own
users which release they need. Section 11.2 has text you can adapt.

## 4. Timeline

<!-- Guidance: Give dates with times and a time zone, and say what changes at each milestone. Questions: does the notice period meet the policy minimum and any contractual notice terms? Are there brownouts, and are they announced in advance? Is there a freeze on new adopters? Pitfall: a sunset that falls on a weekend, a public holiday or a peak trading day for the readers. -->

| Milestone | Date and time (UTC) | What changes for you |
|---|---|---|
| Announcement | *Example:* 2026-10-26 | This notice is published. Responses from `/v1/orders` start to carry `Deprecation` (with the future date 2026-11-02), `Sunset` and `Link` headers; behaviour does not change |
| Deprecation | *Example:* 2026-11-02 00:00 | v1 receives security and severe defect fixes only. New-adopter freeze: accounts with no v1 traffic in the 90 days before this date can no longer start calling v1 |
| Reminder (90 days) | *Example:* 2027-08-19 | Email to every account that still has v1 traffic; last day to request an extension |
| First brownout | *Example:* 2027-09-28 14:00 to 14:15 | v1 returns `503` for 15 minutes so that hidden dependencies surface |
| Reminder (30 days) | *Example:* 2027-10-18 | Email to accounts that still have v1 traffic |
| Second brownout | *Example:* 2027-10-26 14:00 to 15:00 | v1 returns `503` for 60 minutes |
| Final reminder (7 days) | *Example:* 2027-11-10 | Email to every account that still has v1 traffic |
| Sunset | *Example:* 2027-11-17 23:59:59 | v1 stops responding as described in section 9 |
| Notice archived | *Example:* 2028-11-17 | This page moves to the deprecation archive |

*Example:* The dates apply Corvid Commerce's API Versioning and
Deprecation Policy defaults for public APIs: a public deprecation period
of at least 12 months (2026-11-02 to 2027-11-17), no new consumers from
the deprecation date, reminders 90, 30 and 7 days before the sunset,
brownouts only in the last 8 weeks (from 2027-09-22), and extensions of
at most 3 months. The sunset falls on a Wednesday that is not a public
holiday in the United States or the United Kingdom and is clear of the
late-November retail peak in the following week.

```mermaid
flowchart LR
    A[Announced, headers on<br/>2026-10-26] --> B[Deprecated and frozen<br/>2026-11-02]
    B --> C[90-day reminder<br/>2027-08-19]
    C --> D[Brownouts<br/>2027-09-28 and 2027-10-26]
    D --> E[Final reminder<br/>2027-11-10]
    E --> F[Sunset<br/>2027-11-17 23:59:59 UTC]
    F --> G[Archived<br/>2028-11-17]
```

Brownouts are short, announced periods in which the deprecated item
fails on purpose. They find integrations that nobody is watching, such
as a nightly job on a forgotten server, while there is still time to fix
them. Announce each brownout at least [7] days ahead on the status page
and in the changelog, run it at a time of low traffic for most readers,
and never run one during a declared incident.

If the timeline changes, publish a new version of this notice, add a
revision history row, update the `Sunset` header value, and tell affected
readers by email. Move dates later, never earlier, unless security
requires it.

## 5. Replacement and feature mapping

<!-- Guidance: Show how every deprecated capability maps to its replacement, including the ones that have no direct equivalent. Questions: is anything removed without replacement? Does the replacement have different limits, pricing or permissions? Pitfall: claiming feature parity when a niche capability is missing; readers find out during migration and lose trust. -->

| Old capability | New capability | Difference you must handle |
|---|---|---|
| *Example:* `page` and `per_page` query parameters | `cursor` and `limit` | Store the `next_cursor` value instead of incrementing a page number |
| *Example:* `order.total` as a JSON number | `order.total_amount.value` as a decimal string, plus `currency` | Parse the string as a decimal type, not a float |
| *Example:* Retries on `POST /v1/orders` could create duplicates | `Idempotency-Key` header, required | Generate one key per logical order and reuse it on retry |
| *Example:* `status` values `new`, `paid`, `shipped` | Adds `cancelled` (and `partially_shipped` from API 2.4.0) | Handle unknown values without failing |
| *Example:* Filter by `customer_email` | Still accepted in v2 but deprecated (DEP-002, sunset 2027-12-01); filter by `customer_id` | Look up the customer ID first with the Customers API, so you migrate this filter only once |
| [Old] | [New] | [Difference] |

**Permissions and limits.** *Example:* v2 uses the same API keys and
scopes. The default rate limit is the same; burst limits are higher.

**Pricing.** *Example:* No change. Calls to v2 are billed the same way as
calls to v1.

## 6. Migration steps

<!-- Guidance: Give the shortest safe path from old to new as numbered steps a reader can follow and tick off. Put long explanations and edge cases in the Migration Guide (`docs/migration-guide`) and link to it. Questions: can the reader migrate gradually, operation by operation? How do they test without affecting production? How do they roll back? Pitfall: steps that only work for the official SDK, leaving raw HTTP users without guidance. -->

Follow these steps in order. Most readers can migrate one operation at a
time, because v1 and v2 read and write the same orders.

1. **Find your usage.** Use section 7 to list every place that calls
   `/v1/orders` or uses SDK 4.x. Record each one as a migration item.
2. **Upgrade the SDK** (if you use one) to version 5.0.0 or later. Read
   the SDK release notes for other changes in the major version.
3. **Change list calls to cursor pagination.** Replace page counters with
   the `next_cursor` loop shown in the migration guide.
4. **Change money handling.** Read `total_amount.value` as a decimal and
   always store it with `total_amount.currency`.
5. **Add idempotency keys** to every create call, generated once per
   logical order and reused on retry.
6. **Accept new status values.** Make sure unknown values are logged, not
   treated as errors.
7. **Switch webhooks to v2 payloads** in the dashboard under
   [Settings > Webhooks], one endpoint at a time.
8. **Test in the sandbox.** The sandbox already behaves as production
   will after sunset: v1 calls there fail with the sunset response.
9. **Deploy and watch.** After deploying, confirm that the `Deprecation`
   header no longer appears in your logs and that the usage report in
   section 7.1 shows zero v1 calls for at least 7 days.
10. **Remove old code paths** once you see zero v1 traffic, so that
    nobody reintroduces them.

| Step | Owner | Due | Status |
|---|---|---|---|
| *Example:* Inventory v1 calls in the warehouse sync service | [@integration-owner] | 2026-12-15 | Done |
| *Example:* Upgrade SDK to 5.x in the storefront | [@frontend-lead] | 2027-03-31 | In progress |
| *Example:* Switch webhook endpoints to v2 payloads | [@integration-owner] | 2027-06-30 | Not started |
| [Step] | [@owner] | YYYY-MM-DD | [Status] |

**Rolling back.** Until the sunset date you can switch an integration
back to v1 if v2 causes a problem; you will see the deprecation headers
again. After the sunset date there is no rollback, so finish testing
early.

## 7. How to detect usage

<!-- Guidance: Readers cannot migrate what they cannot find. Offer at least two independent ways to detect usage: one from your side (a report) and one from theirs (headers, logs, SDK warnings, code search). Pitfall: relying only on email; the person who receives it is rarely the person who owns the code. -->

### 7.1 Usage report

*Example:* The dashboard page [Developers > Deprecations] lists, for each
API key, the number of calls to deprecated operations in the last 90 days,
the last call time, the user agent and the source IP range. The report is
also available from the `GET /v2/usage/deprecations` operation so that you
can add it to your own monitoring.

The report shows aggregated counts per key and operation. It does not
include request bodies or personal data.

### 7.2 Response headers in your logs

From the announcement date, every response from a deprecated operation
carries `Deprecation`, `Sunset` and `Link` headers; until the deprecation
date the `Deprecation` value is a future date. Search
your HTTP client logs or API gateway logs for these field names. Section
8 explains their values.

### 7.3 SDK warnings

*Example:* SDK 4.8 and later log a warning the first time per process
that a deprecated method is called, with the method name, the sunset date
and a link to this page. Set the log level to `WARNING` or lower to see
it. The warning never contains request data.

### 7.4 Code search

Search your repositories for the identifiers in section 2.1. Useful
patterns:

```text
/v1/orders
orders.list(page=
order.total
"api_version": "1"
corvid-commerce==4.     (Python lock files)
"@corvid/commerce": "^4 (JavaScript lock files)
```

### 7.5 Contract tests

If you keep a copy of our OpenAPI description, the deprecated operations
and parameters are marked `deprecated: true`. A linter rule that fails
your build when you reference a deprecated operation catches new usage
before it ships.

## 8. Machine-readable signals

<!-- Guidance: Document the exact header values that clients will see, so that readers can automate detection. Copy the values from the running service, not from memory. Questions: does the header apply to one resource or to the whole API, and is that scope documented here? Pitfall: a Sunset date earlier than the Deprecation date, or a Deprecation value written as an HTTP-date instead of a structured-field date. -->

### 8.1 Deprecation header (RFC 9745)

The `Deprecation` response header says that the resource is deprecated
or will be deprecated. Its value is a structured-field Date as defined in
RFC 9651: the `@` character followed by the number of seconds since
1970-01-01T00:00:00Z. A date in the past means the resource is already
deprecated; a date in the future announces when deprecation takes
effect. The header does not change how the resource behaves.

*Example:* the deprecation date 2026-11-02T00:00:00Z is `@1793577600`.
Corvid Commerce sends this value from the announcement on 2026-10-26, when
it is still a future date, so that clients see the coming deprecation a
week early.

### 8.2 Sunset header (RFC 8594)

The `Sunset` response header gives the time after which the resource is
expected to become unresponsive. Its value is an HTTP-date (the IMF-fixdate
format, always in GMT). RFC 9745 requires that the sunset time is not
earlier than the deprecation time.

*Example:* the sunset time 2027-11-17T23:59:59Z is
`Wed, 17 Nov 2027 23:59:59 GMT`.

### 8.3 Link relations

Two `Link` header relations point readers to documentation:

- `rel="deprecation"` (RFC 9745) links to information about the
  deprecation, such as this notice or the migration guide.
- `rel="sunset"` (RFC 8594) links to information about the sunset or the
  retirement policy.

### 8.4 Example response

A response from a deprecated Orders API v1 operation looks like this
(*Example*):

```http
HTTP/1.1 200 OK
Content-Type: application/json
Deprecation: @1793577600
Sunset: Wed, 17 Nov 2027 23:59:59 GMT
Link: <https://developer.example.com/deprecations/orders-v1>; rel="deprecation"; type="text/html"
Link: <https://developer.example.com/policies/api-deprecation>; rel="sunset"; type="text/html"
```

### 8.5 Scope

By default, both headers apply only to the resource that returned them.
If you send them on a single entry point but mean the whole API version,
say so here, because clients that do not read this page will assume the
narrow scope. *Example:* Corvid Commerce sends both headers on every
response under `/v1/orders`, so the scope is per resource and needs no
extra explanation.

### 8.6 Description documents and schemas

| Format | Signal | *Example* |
|---|---|---|
| OpenAPI 3.2.1 (3.1.x also widely used) | `deprecated: true` on the Operation, Parameter and Header Objects; `deprecated: true` in the Schema Object for properties | `listOrders` operation marked deprecated |
| AsyncAPI 3.1.0 | `deprecated: true` in the Schema Object of the message payload | `OrderUpdatedV1` payload schema marked deprecated |
| GraphQL | `@deprecated(reason: "...")` on fields and enum values | Reason text names the sunset date and replacement |
| SDKs | Language-native deprecation markers (annotations, decorators, doc tags) | `@deprecated` JSDoc tag on `orders.list(page)` |

```yaml
# OpenAPI 3.2.1 fragment (Example)
paths:
  /v1/orders:
    get:
      operationId: listOrders
      deprecated: true
      description: >
        Deprecated on 2026-11-02, sunset 2027-11-17. Use listOrdersV2.
```

### 8.7 Client guidance

Treat both headers as hints, not guarantees. A deprecated resource keeps
working until its sunset, but readers should not assume it will. Have
your monitoring alert when either header first appears, and fetch linked
documentation over HTTPS only.

## 9. What happens at sunset

<!-- Guidance: Describe exactly what callers will see after the sunset time, so that they can recognise it in an incident. Questions: which status code and error body? Is there a grace period? Is data deleted or kept? Pitfall: an undocumented sunset response that looks like an outage, which floods support. -->

| Aspect | Behaviour after the sunset time |
|---|---|
| HTTP status | *Example:* `410 Gone` for every `/v1/orders` operation |
| Error body | *Example:* `{"error": {"code": "api_version_sunset", "message": "Orders API v1 was retired on 2027-11-17. Use /v2/orders.", "doc_url": "https://developer.example.com/deprecations/orders-v1"}}` |
| Webhooks | *Example:* v1 payloads are no longer delivered; endpoints still on v1 are switched to v2 automatically and an email is sent |
| SDK 4.x | *Example:* Calls fail with `ApiVersionSunsetError`; no new 4.x releases |
| Your data | *Example:* Unchanged and available through v2 |
| Grace period | *Example:* None. Do not plan on one |
| Status page | *Example:* The sunset is listed as planned maintenance, not as an incident |

Use a status code that matches the behaviour you choose: a permanent
removal is usually signalled with `410 Gone`, a redirect to the
replacement with a `3xx` code only when the request can be served
unchanged by the new version. Keep the error body stable so that readers
can match on its code.

## 10. Support and extensions

<!-- Guidance: Explain how to get help and whether exceptions exist. Questions: who decides on an extension, what evidence is needed, and what is the latest possible date? Pitfall: granting quiet extensions to some customers, which makes the public date meaningless and the next deprecation harder. -->

| Topic | Details |
|---|---|
| Help with migration | *Example:* Developer forum tag `orders-v2`, support ticket category "API migration", office hours every Tuesday 15:00 UTC until the sunset date |
| Enterprise customers | *Example:* Your account manager can arrange a migration review |
| Extension requests | *Example:* Submit through the support portal by 2027-08-19 with the integration name, call volume, blocking reason and planned completion date; extensions are granted only under the policy, to named API keys, and never beyond 2028-02-17 (3 months after the sunset) |
| Partner and marketplace apps | *Example:* The partner directory marks apps that already use v2 |
| Contract terms | *Example:* Customers with contractual notice terms receive notice under those terms; this public notice does not change any agreement |

Extensions, if granted, apply to named API keys only and are recorded in
the internal deprecation register. The public sunset date does not move
for anyone else.

## 11. Announcement variants

<!-- Guidance: Publish the same facts in three formats. The page is the source of truth; the email and the changelog entry link to it. Questions: who receives the email (technical contacts, account owners, both)? In which languages? Pitfall: an email with different dates from the page because it was drafted separately. -->

### 11.1 Documentation page

This document is the page variant. Publish it at the canonical URL in
the Document control table, link it from the API reference for every
deprecated operation, from the migration guide, from the changelog and
from the `Link` header with `rel="deprecation"`. Add a short banner at the
top of each deprecated reference page:

```text
Deprecated: Orders API v1 stops working on 17 November 2027 at 23:59:59 UTC.
Move to Orders API v2. See the deprecation notice for steps.
```

### 11.2 Email

Send the email to the technical contacts on each affected account (from
the usage report), with a copy to the account owner. Use plain text or
simple HTML, no tracking pixels, and the same dates as section 1.

```text
Subject: Action required by 17 November 2027: move from Orders API v1 to v2

Hello [Contact name],

Your account [Account name] called Orders API v1 [N] times in the last
90 days. Orders API v1 is deprecated from 2 November 2026 and will stop
working on 17 November 2027 at 23:59:59 UTC.

What to do:
1. Move your integration to Orders API v2.
2. If you use our SDK, upgrade to version 5.0.0 or later.
3. Confirm in [Developers > Deprecations] that v1 calls have stopped.

Most integrations need one to three days of work including testing.
Migration guide: [URL]
Full notice: [URL]

Need help? Reply to this email or open a ticket in the category
"API migration".

[Team name]
You receive this message because you are a technical contact for an
account that uses Orders API v1. This is a service message about your
use of the product.
```

### 11.3 Changelog entry

Add the entry to the API Changelog (`docs/api-changelog`) under the date
the headers and the `deprecated: true` flags reach production (*Example:*
the announcement date, 2026-10-26), with the deprecation and sunset dates
in the entry, classified as a deprecation that becomes breaking at sunset,
and link it to this page.

```markdown
### 2026-10-26: Orders API v1 deprecation announced (APICHG-015)

**Class:** Deprecation (breaking at sunset)
**Affects:** all operations under `/v1/orders`; SDK 4.x
**Deprecation:** 2026-11-02 (`Deprecation: @1793577600`)
**Sunset:** 2027-11-17 23:59:59 UTC (`Sunset: Wed, 17 Nov 2027 23:59:59 GMT`)
**Replacement:** Orders API v2; SDK 5.0.0 and later
**Read:** [Deprecation notice](URL), [Migration guide](URL)
```

### 11.4 Reminder schedule

| When | Channel | Audience |
|---|---|---|
| *Example:* Announcement day (2026-10-26) | Email, changelog, blog, dashboard banner; headers start | All accounts with v1 traffic in the last 90 days |
| *Example:* Deprecation day (2026-11-02) | Changelog, dashboard banner; new-adopter freeze starts | All |
| *Example:* 90, 30 and 7 days before sunset (2027-08-19, 2027-10-18, 2027-11-10) | Email | Accounts still sending v1 traffic |
| *Example:* 7 days before each brownout | Status page, changelog | All |
| *Example:* Sunset day | Status page, changelog | All |
| [When] | [Channel] | [Audience] |

Stop emailing an account as soon as its v1 traffic reaches zero. Repeated
reminders to readers who have already migrated teach them to ignore the
next notice.

## 12. Frequently asked questions

<!-- Guidance: Answer the questions support expects, in the reader's words. Add new questions as tickets arrive and record the change in the revision history. Pitfall: questions that nobody asked, written to repeat marketing points. -->

**Will my v1 integration stop working on the deprecation date?**
*Example:* No. It keeps working until the sunset date, apart from the two
announced brownouts. The headers start at the announcement; the
deprecation date ends new features for v1 and stops accounts that have
never used v1 from starting.

**Can I use v1 and v2 at the same time?**
*Example:* Yes. Both read and write the same orders, so you can migrate
one operation at a time.

**Do I need new API keys?**
*Example:* No. Existing keys and scopes work with v2.

**What if a third-party app I use still calls v1?**
*Example:* Contact the app vendor. The partner directory shows which apps
have migrated. The usage report shows the app's user agent so that you
can tell which app is calling.

**Can I get more time?**
*Example:* Only under the extension process in section 10, with a request
by 2027-08-19. Extensions apply to named API keys and end by 2028-02-17
at the latest.

**Where do I report a problem with v2?**
*Example:* Open a support ticket in the category "API migration". Check
Known Issues (`docs/known-issues`) first for current workarounds.

## 13. Pre-publication checklist

<!-- Guidance: Run this checklist before publishing and again before each reminder. Pitfall: publishing the page before the headers or the usage report exist, so readers cannot follow the instructions. -->

| ID | Check | Done |
|---|---|---|
| CHK-001 | Dates in sections 1, 4, 8, 11 and the email match exactly | [ ] |
| CHK-002 | Notice period meets the deprecation policy and contractual terms | [ ] |
| CHK-003 | Sunset date is not earlier than deprecation date, not on a weekend, public holiday or known peak | [ ] |
| CHK-004 | `Deprecation` value is a structured-field date (`@` plus seconds) and decodes to the stated date | [ ] |
| CHK-005 | `Sunset` value is an HTTP-date in GMT and decodes to the stated time | [ ] |
| CHK-006 | Both `Link` relations resolve over HTTPS to live pages | [ ] |
| CHK-007 | OpenAPI and AsyncAPI descriptions mark deprecated items and are published | [ ] |
| CHK-008 | Usage report works and contains no personal data beyond what support already sees | [ ] |
| CHK-009 | Migration guide is published and tested by someone outside the team | [ ] |
| CHK-010 | Support has the FAQ, the extension process and a ticket category | [ ] |
| CHK-011 | Sunset behaviour (status code, error body) is implemented in the sandbox | [ ] |
| CHK-012 | Email reviewed for tone, dates and links; no tracking pixels | [ ] |
| CHK-013 | Localised versions (if any) show the same dates and links | [ ] |

## 14. Glossary and references

<!-- Guidance: Define terms the way readers will meet them in the headers and the email. Pitfall: using "deprecated" and "removed" as synonyms. -->

### 14.1 Glossary

| Term | Meaning in this notice |
|---|---|
| Deprecation | The item still works but is no longer recommended and will be retired; no new features are added |
| Sunset | The time after which the item is expected to stop responding |
| Brownout | A short, announced, deliberate failure of a deprecated item to reveal hidden usage |
| Replacement | The supported item that readers should move to |
| Structured-field Date | An HTTP field value type: `@` followed by seconds since 1970-01-01T00:00:00Z (RFC 9651) |
| HTTP-date | The fixed date format used in HTTP fields, for example `Wed, 17 Nov 2027 23:59:59 GMT` |
| Link relation | A named relationship in a `Link` header, such as `deprecation` or `sunset` |
| New-adopter freeze | The point after which accounts that never used the item cannot start |

### 14.2 References

| Reference | Version or date | Use in this template |
|---|---|---|
| RFC 9745, The Deprecation HTTP Response Header Field (S. Dalal, E. Wilde), rfc-editor.org | Standards Track, March 2025 | `Deprecation` header syntax and semantics, `deprecation` link relation, scope, relation to `Sunset` |
| RFC 8594, The Sunset HTTP Header Field (E. Wilde), rfc-editor.org | Informational, May 2019 | `Sunset` header, `sunset` link relation, scope and past-date handling |
| RFC 9651, Structured Field Values for HTTP, rfc-editor.org | Standards Track, September 2024 | Date type used by `Deprecation` (section 3.3.7) |
| RFC 9110, HTTP Semantics, rfc-editor.org | Standards Track, June 2022 | HTTP-date format, `410 Gone` |
| RFC 8288, Web Linking, rfc-editor.org | Standards Track, October 2017 | `Link` header syntax |
| OpenAPI Specification, spec.openapis.org | 3.2.1, 2026-09-10 | `deprecated` field on operations, parameters, headers and schemas |
| AsyncAPI Specification, asyncapi.com | 3.1.0, 2026-01-31 | `deprecated` field on schemas |
| Semantic Versioning, semver.org | 2.0.0 | Deprecation in a minor release, removal in a major release |
| [Internal API deprecation policy] | [Version] | Notice periods and exception rules |

## Standard and licence note

Based on IETF RFC 9745 (The Deprecation HTTP Response Header Field,
March 2025) and RFC 8594 (The Sunset HTTP Header Field, May 2019), with
RFC 9651, RFC 9110 and RFC 8288 for field syntax, and on the
`deprecated` fields of the OpenAPI Specification 3.2.1 and the AsyncAPI
Specification 3.1.0 (both published under the Apache License 2.0 by the
OpenAPI Initiative and the AsyncAPI Initiative). Header formats are
described in original words and the example values were computed for
this template; no RFC or specification text is reproduced. Corvid
Commerce and every example value are fictional. This template is
original text written for this collection. Check the current RFC status
and specification versions before use. Template licence: MIT.