Deprecation Notice Template (RFC 9745, RFC 8594)

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.

Document control

Approvals

Revision history

Contents

1. Notice summary
2. What is changing
3. Who is affected
4. Timeline
5. Replacement and feature mapping
6. Migration steps
7. How to detect usage
8. Machine-readable signals
9. What happens at sunset
10. Support and extensions
11. Announcement variants
12. Frequently asked questions
13. Pre-publication checklist
14. Glossary and references

1. Notice summary

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

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

2.2 Not affected

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

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

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

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.

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

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

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.

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

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:

/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

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

# 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

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

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

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:

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.

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.

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

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

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

14. Glossary and references

14.1 Glossary

14.2 References

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.