# API Sunset Notification

> Use when performing api sunset notification — template for managing API sunset notifications and deprecation communications. Covers consumer identification, multi-channel notification strategy, deprecation header implementation, migration tracking, escalation procedures, and sunset enforcement to ensure smooth API retirement.

- Skill: `cloudthinker-ai/api-sunset-notification` (Agent Skill)
- Install (CLI): `npx skillmds@latest add cloudthinker-ai/api-sunset-notification`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cloudthinker-ai/api-sunset-notification/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: cloudthinker-ai (https://skillmd.com/u/cloudthinker-ai)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/cloudthinker-ai/api-sunset-notification

---


# API Sunset Notification Skill

Manage sunset of **{{ api_name }} {{ api_version }}** on **{{ sunset_date }}** (replacement: **{{ replacement_version }}**).

## Workflow

### Phase 1 — Consumer Identification

```
API CONSUMER MAP
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[ ] Total active consumers: ___
[ ] Consumer inventory:
    Consumer          | API Key/Client | Daily Calls | Contact     | Priority
    __________________|________________|_____________|_____________|_________
                      |                |             |             |
                      |                |             |             |
                      |                |             |             |

[ ] Consumers by type:
    - Internal services: ___
    - External partners: ___
    - Public developers: ___
[ ] Endpoints most used:
    - ___: ___ calls/day
    - ___: ___ calls/day
    - ___: ___ calls/day
```

### Phase 2 — Notification Strategy

```
COMMUNICATION CHANNELS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[ ] API response headers:
    Deprecation: true
    Sunset: {{ sunset_date }}
    Link: <migration-guide-url>; rel="successor-version"

[ ] Direct communication:
    [ ] Email to registered API consumers
    [ ] Partner portal notification
    [ ] Developer portal banner
    [ ] Changelog entry

[ ] Documentation:
    [ ] Migration guide published
    [ ] API diff ({{ api_version }} vs {{ replacement_version }})
    [ ] Code examples for migration
    [ ] FAQ document

NOTIFICATION SCHEDULE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Date          | Action                    | Channel          | Status
______________|___________________________|__________________|_______
T-6 months    | Initial announcement      | All channels     | [ ]
T-3 months    | Migration reminder        | Email + headers  | [ ]
T-2 months    | Usage report to consumers | Email            | [ ]
T-1 month     | Final warning             | All channels     | [ ]
T-2 weeks     | Last call                 | Direct contact   | [ ]
T-0           | Sunset enforcement        | API returns 410  | [ ]
```

### Phase 3 — Migration Tracking

```
MIGRATION STATUS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[ ] Migration dashboard deployed
[ ] Tracking metrics:
    - {{ api_version }} daily request count: ___
    - {{ replacement_version }} daily request count: ___
    - Migration percentage: ___%

    Consumer          | Status        | {{ api_version }} Calls | {{ replacement_version }} Calls
    __________________|_______________|________________________|___________________________
                      | NOT STARTED   |                        |
                      | IN PROGRESS   |                        |
                      | COMPLETED     |                        |

[ ] Consumers requiring assistance:
    - ___: blocker: ___
    - ___: blocker: ___
```

### Phase 4 — Escalation and Enforcement

```
ESCALATION PROCEDURES
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
For unmigrated consumers at T-1 month:
[ ] Direct outreach by account manager / developer relations
[ ] Technical support session offered
[ ] Extension request process:
    - Maximum extension: ___
    - Approval required from: ___
    - Extension granted to: ___

ENFORCEMENT
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[ ] Gradual enforcement (optional):
    [ ] T-2 weeks: Rate limit {{ api_version }} to 50% of current
    [ ] T-1 week: Rate limit {{ api_version }} to 10% of current
    [ ] T-0: Return 410 Gone with migration link
[ ] Hard enforcement:
    [ ] T-0: Immediately return 410 Gone
[ ] 410 response body includes:
    [ ] Migration guide URL
    [ ] {{ replacement_version }} endpoint URL
    [ ] Support contact information
```

### Phase 5 — Post-Sunset

```
POST-SUNSET CLEANUP
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[ ] {{ api_version }} traffic at zero for ___ days
[ ] {{ api_version }} code removed or archived
[ ] {{ api_version }} documentation marked as sunset
[ ] API gateway routes removed
[ ] {{ api_version }}-specific infrastructure decommissioned
[ ] Lessons learned documented:
    - Total migration duration: ___
    - Consumers that required extensions: ___
    - Improvements for next sunset: ___
```

## Counter-Rationalizations

| Shortcut | Counter | Why |
|----------|---------|-----|
| "We can skip some steps for this case" | Adapt the workflow steps, don't skip them | Skipped steps are where incidents and oversights originate |
| "The user seems to already know what to do" | Complete all workflow phases with the user | The workflow catches blind spots that experience alone misses |
| "This is a minor case, full process is overkill" | Scale the process down, don't turn it off | Minor cases become major when unstructured; the process scales, not disappears |
| "I'll fill in the details later" | Complete each section before moving on | Deferred details are forgotten; real-time capture is more accurate |
| "The template output isn't necessary" | Always produce the structured output format | Structured output enables comparison, audit trails, and handoff to other teams |

## Output Format

Produce an API sunset management report with:
1. **Consumer analysis** (who is affected, usage volumes)
2. **Notification log** (communications sent, dates, channels)
3. **Migration progress** (consumer-by-consumer status)
4. **Escalations** (unmigrated consumers, extensions granted)
5. **Post-sunset status** (cleanup completed, lessons learned)