Product Change Management Plan — API Deprecation (Lumadeck Reporting API v1)

Product / area: Lumadeck Reporting API (fictional analytics platform) Change owner: Reza Haddad, Product Manager — Platform Change type: Deprecation (breaking, with migration runway) Version: v1.2 Drafted: 14 January 2026 Target release: v1 retired 1 July 2026

---

1. Change summary and rationale

We are deprecating version 1 of the Reporting API and moving all customers to version 2. The v1 endpoints will keep working until 1 July 2026, after which they will return an error. v2 has been live and stable for nine months; it is faster, paginated, and exposes the new metrics customers keep requesting. Keeping v1 alive means maintaining two code paths and a brittle data layer that already blocks three roadmap items.

• What is changing: Reporting API v1 endpoints are deprecated and will be switched off on 1 July 2026.
• Why now: v2 is mature, and v1 is blocking the new dashboard work and doubling our maintenance load.
• Cost of doing nothing: Continued double maintenance, no path to the requested metrics, growing risk.

2. Impact assessment

Area	Impact	Severity
API consumers on v1	Must migrate calls to v2 or break after 1 July	High
Large enterprise integrations	Custom report jobs reference v1 field names	High
Self-serve customers	Mostly already on v2; a minority still on v1	Medium
Documentation	v1 reference must be marked deprecated, v2 promoted	Low
Support	Expect migration questions through the runway period	Medium

3. Affected stakeholders and customers

Telemetry shows 38 active accounts still calling v1, of which 6 are enterprise contracts with custom report jobs. Those 6 are the priority: they are most affected and were informed first, by name, with a dedicated migration contact. The remaining 32 self-serve accounts are handled with email plus an in-app banner. Support and the success team were briefed a week before any customer notice went out.

4. Approval

Approver	Role	Decision	Date
Reza Haddad	Product Manager	Approved	16 January 2026
Ingrid Sato	Engineering Lead, Platform	Approved	17 January 2026
Daniel Cruz	Head of Customer Success	Approved	17 January 2026

5. Communication plan and timeline

Audience	Message	Channel	Timing
Support + Success	Full briefing, migration FAQ, contact for each enterprise account	Internal note + call	20 Jan (week before)
6 enterprise accounts	Named email, deadline, migration guide, dedicated engineer	Direct email + call	27 Jan (5 months notice)
32 self-serve v1 accounts	What is changing, deadline, how to migrate	Email + in-app banner	27 Jan
All API users	Deprecation notice and v2 guide	Changelog + docs banner	27 Jan, repeated 1 Apr, 1 Jun

6. Rollout and rollback

v1 stays fully live through the runway. From 1 June, v1 responses carry a deprecation header and a Sunset date so any new integration is warned. On 1 July, v1 returns a 410 with a link to the v2 guide.

• Rollout method: Time-boxed deprecation with a deprecation header from 1 June and shutdown on 1 July.
• Signals to watch: Count of accounts still on v1 each week; target zero active enterprise accounts by 1 June.
• Rollback trigger: More than 2 enterprise accounts still actively on v1 in the final week.
• Rollback steps: Extend the v1 Sunset date by a defined grace period and re-notify; the toggle is config-only and takes minutes.
• Who can call it: Reza Haddad, in consultation with Ingrid Sato.
• If irreversible: Not applicable — v1 can be kept alive by configuration until every priority account has migrated.

7. Success criteria

• Zero active enterprise accounts on v1 by 1 June 2026.
• All 38 v1 accounts migrated or confirmed inactive by 1 July 2026.
• No unplanned support spike attributable to the deprecation during the runway.
• v1 maintenance code removed within one sprint of shutdown, unblocking the dashboard roadmap.