01 · Definition
What is Graph API versioning?
Graph API versioning is Meta's system for changing its API without breaking existing integrations. Every request names a version in its path — https://graph.facebook.com/v26.0/{PHONE_NUMBER_ID}/messages — and Meta keeps the behaviour of that version, including the WhatsApp Cloud API endpoints served on it, stable for at least two years. Breaking changes, renamed fields and removed parameters land in a new version; your code meets them only when you change the number in the path.
Versions are numbered vXX.0 and released several times a year, each with a dated changelog entry. A version stops being usable two years after its successor ships: v25.0 shipped on 18 February 2026, so v24.0 (released 8 October 2025) remains available until 18 February 2028. The current Graph API version is v26.0, released on 29 July 2026. A call that leaves the version out uses the app's default version set in the App Dashboard, and a call to an expired version is routed to the oldest version still available.
Versioning is not the same as API Deprecation. Versioning is the routine cycle of dated releases and how you pin, test and upgrade; deprecation is a product or feature being retired outright — such as the On-Premises API, sunset on 23 October 2025 — whichever version you call. Pricing and policy decisions, such as per-message pricing or the India charge for service messages since 1 October 2026, also apply across every version at once.
Key takeaways
- Every Graph API call names a version in its path, such as /v26.0/; behaviour is fixed per version, not per release day.
- A version works for at least two years and stops being usable two years after the next version ships.
- v26.0, released 29 July 2026, is the current version; v21.0 stops working on 21 January 2027.
- Calls to an expired version are routed to the oldest version still available, which can change behaviour on Meta's date.
- Pricing and policy changes apply whatever version you call, so pinning a version never freezes everything.
02 · Specifications
Graph API versioning: key facts and limits
| Format | /vXX.0/ in the request path |
|---|---|
| Current version | v26.0, released 29 July 2026 |
| Minimum life | At least 2 years from release |
| End-date rule | 2 years after the next version ships |
| v24.0 | Released 8 October 2025, usable until 18 February 2028 |
| v21.0 | Usable until 21 January 2027 |
| Expired version called | Routed to the oldest version still available |
| No version in path | App Dashboard default version is used |
03 · Operation
How does Graph API versioning work?
Pin the version in one place
Keep the version in a single configuration value and build every Graph URL from it. Never rely on unversioned calls or on the App Dashboard default.
Track the end date
Your pinned version stops two years after the next version's release. Note that date in your runbook and put an upgrade deadline in the team calendar months ahead.
Read every changelog in between
Meta's changelog lists changes per version. Read each entry between your current and target version for the Cloud API, template and business management endpoints you use.
Test with only the version changed
Run your integration tests against the new version — sends through the Messages Endpoint, template creation, media upload, reads and error handling — on a test number before touching production.
Roll out gradually and watch errors
Ship the new version to one sending number or a share of traffic first, compare error codes and latency, then move everything. Keep the old value ready to roll back.
Upgrade the app default too
Once code is on the new version, upgrade the app's default version in the App Dashboard so any stray unversioned call behaves the same way.
04 · Code samples
Graph API versioning in code
// One place for the version: change it, test it, ship it.const GRAPH_VERSION = process.env.GRAPH_VERSION ?? "v26.0";const GRAPH = "https://graph.facebook.com/" + GRAPH_VERSION;export async function sendMessage(phoneNumberId, payload) {const res = await fetch(GRAPH + "/" + phoneNumberId + "/messages", {method: "POST",headers: {Authorization: "Bearer " + process.env.ACCESS_TOKEN,"Content-Type": "application/json",},body: JSON.stringify(payload),});// Record which version actually served the callconst served = res.headers.get("facebook-api-version");if (served && served !== GRAPH_VERSION) console.warn("Served by " + served);return res.json();}
A mismatch between the pinned and served version is the early warning that a version has expired or a call is unversioned.
05Playground
A working model of Graph API Versioning. Use its controls to replay it step by step.
Scrub the Graph API version calendar
29 Jul 2028Coming upEvent 9 of 9
v25.0 expected end
Two years after v26.0 under the published rule — confirm the date in Meta's changelog.
Event 9 of 9: 29 Jul 2028 — v25.0 expected end (coming up). Two years after v26.0 under the published rule — confirm the date in Meta's changelog.
06 · Cautions
Common mistakes with Graph API versioning
Relying on unversioned calls
A call without a version uses the App Dashboard default, which anyone with access can upgrade — changing your behaviour without a deploy. Put the version in every path.
Hard-coding versions across the codebase
A version string copied into twenty files means twenty edits and one forgotten. Keep it in one config value and grep for stray
/vNN.0/literals in CI.Letting a version expire
Expired calls are routed to the oldest available version, so changed fields and validation hit production on Meta's date. Upgrade well before the end date, not on it.
Assuming the version freezes everything
Pricing, policy and product retirements apply whatever version you call. Follow WhatsApp platform announcements as well as the Graph changelog.
07 · Rationale
Why does Graph API versioning matter?
An integration that never touches its version number works until the day it does not. When the pinned version expires, calls quietly move to a newer one, and changed fields or stricter validation can break sends, template creation or response parsing all at once, on Meta's calendar rather than yours. Treating the version as configuration — tested, upgraded on a schedule and recorded in release notes — turns a forced migration into routine maintenance, and lets you adopt new WhatsApp features on purpose.
08 · Worked example: Planning the v21.0 exit
Example: Planning the v21.0 exit
A Kochi insurance broker's WhatsApp renewal service still calls v21.0, which stops working on 21 January 2027. In October 2026 the team moves the version into an environment variable, reads the changelogs from v22.0 to v26.0 for the message, media and template endpoints it uses, and runs its test suite against v26.0 on a test number. One template-creation payload needs a change; everything else passes. They move one sending number to v26.0 for a week, watch error rates, then switch the rest — three months before the deadline instead of on it.
09 · Recommended practice
Best practices for Graph API versioning
- When several versions behind, read every changelog in between, even if you jump straight to the newest.
- Log the
facebook-api-versionresponse header to confirm which version served each call. - Upgrade test and staging apps first, then production.
- If you call the API through an SDK, check which version it pins — wrappers often hard-code one you must override or upgrade with the library.
- If you generate clients from an OpenAPI Specification, regenerate them for the target version and review the diff before merging.
- Record the pinned version and its end date in your runbook next to the token expiry dates.
10 · Questions and answers
Graph API Versioning FAQs
- What is the latest Graph API version?
- v26.0, released on 29 July 2026, is the current Graph API version. Meta lists every version and its release date in the Graph API changelog, and new integrations should start on the current one.
- What happens when a Graph API version expires?
- Calls to it are routed to the oldest version still available. Requests keep working only if nothing they rely on changed in between, so upgrade before the end date instead of trusting the fallback.
- How long is a Graph API version supported?
- At least two years from release; precisely, it stops being usable two years after the next version ships. v24.0, for example, was released on 8 October 2025 and remains available until 18 February 2028.
- Do WhatsApp pricing changes depend on my Graph API version?
- No. Pricing and policy apply regardless of the version in your path. Versions govern request and response behaviour — fields, parameters, validation — not what Meta charges per message.