# Upgrade your integration

> Pin the API version your code expects and move to a newer one safely.

Every Messaging and Platform request runs against a dated API version. Pin the
version your code was written for, so a new version never changes a response
under you, and move to a newer version on your own schedule.

| | Version |
| --- | --- |
| Current | `2026-09-22` |
| Minimum supported | `2026-09-22` |

`2026-09-22` is the only supported version. `2026-03-20` was retired on
October 19, 2026.

## Pin the version

Send the version in the `Polymorfa-Version` header on every request. Without
the header, Polymorfa uses the current version, so your integration changes
behavior when a new version becomes current.

**API:**

```bash cURL
curl https://api.polymorfa.com/platform/sessions \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
```

```typescript TypeScript
import { Client } from "@polymorfa/sdk";

const platform = new Client({
  credential: { type: "organizationApiKey", value: process.env.POLYMORFA_KEY! },
  apiVersion: "2026-09-22",
});

// One request at another version; the response metadata has the version applied.
const numbers = await platform.sessions.list(undefined, { apiVersion: "2026-09-22" });
console.log(numbers.metadata.apiVersion);
```

```bash Graph API
# The Graph API takes its version in the URL, not in Polymorfa-Version.
curl "https://api.polymorfa.com/graph/whatsapp/v26.0/$WABA_ID/phone_numbers" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
```

The response repeats the version it applied in its own `Polymorfa-Version`
header. Log it to confirm what your integration runs against.

*TypeScript:*

Without `apiVersion`, the TypeScript SDK sends the version it was built for,
`2026-09-22` in current releases. Set it explicitly so an SDK update does not
change your API version. You can also pass `apiVersion` on a single request.

**CLI:**

```bash
polymorfa api /platform/sessions --api-version 2026-09-22
```

Every CLI command accepts `--api-version` to override the version for that
command.

Graph requests do not use `Polymorfa-Version`. They take a Meta-style version
in the URL, such as `/graph/whatsapp/v26.0`. See
[Graph API versions](https://docs.polymorfa.com/api/versioning#graph-api-versions).

## Watch for deprecation

When you send a version that is still supported but older than the current one,
the response can include:

- `Polymorfa-Deprecation-Warning`, describing the change;
- `Sunset`, the date the version stops working; and
- `Link` with `rel="sunset"`, pointing to upgrade guidance.

Log these headers and alert on them. After the sunset date, the version is
below the minimum and requests return `400`
[`invalid_parameter`](https://docs.polymorfa.com/api/errors#invalid-parameter) with
`error.param: Polymorfa-Version`, `Deprecation: true` and a `Link` with
`rel="deprecation"`. See [API versioning](https://docs.polymorfa.com/api/versioning).

## Upgrade to a newer version

### Read what changed

Read the [changelog](https://docs.polymorfa.com/changelog) entries tagged **API** between your version
and the target version. Each entry says who is affected and whether you need
to act.

### Update your SDK

Install the SDK release that supports the target version. Read its
[version notes](#sdk-version-notes) for changes to methods and types.

### Test with the new version

Send the new `Polymorfa-Version` from a test environment, against a
[test number](https://docs.polymorfa.com/testing/test-numbers) where you can. Check the requests and
event handlers that the changelog entries affect.

### Switch production

Change the pinned version in production. Watch your error rate and the
[request logs](https://docs.polymorfa.com/development/request-logs) for `400` and new error codes.

Roll back by sending the previous version, as long as it is still supported.

## SDK version notes

`@polymorfa/sdk` is a development prerelease, and a prerelease can change a
method or a response shape. These are the changes that need action when you
upgrade, newest first. Each version is named `0.1.0-dev.<timestamp>`, so you
can compare yours with the dates below. Check the installed version with
`npm ls @polymorfa/sdk`, or read the `SDK_VERSION` export.

### November 12, 2026

#### Organization is now team

Every SDK name that said organization now says team, with no aliases:

| Before | After |
| --- | --- |
| `{ type: "organizationApiKey" }` | `{ type: "teamApiKey" }` |
| `credentialKind: "organization_api_key"` | `credentialKind: "team_api_key"` |
| `OrganizationClient` | `TeamClient` |
| `client.organizations.*` | `client.teams.*` |
| `orgId`, `organizationId` fields | `teamId` |

Rename these in your code when you install a release from this date or later.

### October 5, 2026

#### Campaign content and sequences

From `0.1.0-dev.20261005230914`, campaign create and update requests accept
`variableMapping` and `trackedLinks`, `messaging.campaigns.update` accepts
`templateId`, `platform.campaigns.create` and `update` type `messagesArray` as
`CampaignMessage[]`, and `LaunchCampaignRequest` accepts
`skipMissingVariables`. `Campaign` records include `trackedLinks`, and campaign
recipients include `messagesSent`, `nextMessageAt` and `sequenceError`. The
version also adds `messaging.campaigns.update`, `reschedule` and
`exportRecipients`, and `platform.audiences.createFromCampaign`. If your code
builds `Campaign` or `CampaignRecipient` objects, add the new fields. See
[Campaigns](https://docs.polymorfa.com/campaigns/send#pick-a-surface).

#### STOP confirmations

From `0.1.0-dev.20261005233122`, organization clients expose
`optOuts.getConfirmationSettings`, `updateConfirmationSettings` and
`getConfirmationSummary`.

### October 1, 2026

#### Flow drafts return the draft in `response.data`

From `0.1.0-dev.20261001124422`, `flows.list` and `flows.retrieve` return the
drafts directly in `response.data`.

`0.1.0-dev.20260926213449` through `0.1.0-dev.20260927174827` returned them in
`response.data.data`. Replace `response.data.data` with `response.data` when you
upgrade. See [Flows](https://docs.polymorfa.com/messaging/flows#manage-drafts-in-code).

#### Campaign send windows

From `0.1.0-dev.20261001124422`, `messaging.campaigns.create`,
`platform.campaigns.create`, and `platform.campaigns.update` accept
`sendWindow`, and campaign records include it. The SDK exports
`CampaignSendWindowRequest` and `CampaignSendWindow`. See
[Campaigns](https://docs.polymorfa.com/campaigns/send#create-the-campaign-with-its-recipients).

### September 26, 2026

#### Flow draft reads

`0.1.0-dev.20260926213449` added `flows.list` and `flows.retrieve` on project
clients.

### September 22, 2026

#### `whatsapp_ids` replaces `whatsapp_id`

API version `2026-09-22` returns WhatsApp message references in `whatsapp_ids`,
under `linked_devices`, `official_api`, or both. SDK message receipts and
webhook types include it. The singular `whatsapp_id` field is deprecated and
remains only while older API versions are supported. Read `whatsapp_ids` in new
code. See [Message IDs](https://docs.polymorfa.com/messaging/ids#message-identifiers).

### September 20, 2026

#### Operations

The SDK added `operations.list`, `get`, `listTransitions`, `wait`, and `cancel`.
See [Events and operations](https://docs.polymorfa.com/development/operations#wait-for-an-operation).

### September 2026

#### Number tier changes use a quote

`sessions.setTierOverride(sessionId, { tierOverride })` was replaced by a quote
and a confirmation. Call `sessions.quoteTierChange`, show the quote, then pass
its ID as `setTierOverride(sessionId, { quoteId })`. Read the result with
`sessions.retrieveTierChange`. See
[Change a Number's tier](https://docs.polymorfa.com/billing/number-tiers#change-a-numbers-tier).

#### Balance warning settings removed

`billing.updateReminderSettings` was removed, and billing responses no longer
include `lowBalanceThresholdCents` or `reminderChannels`. Configure balance
warnings in the Console under **My notifications**.

Credit amounts in balances, usage, and BanSafe claims can have up to six decimal
places, including fields whose names end in `Cents`. Do not parse them as
integers.

#### QuickLink replaces direct Number creation

`sessions.create` and `sessions.createTesting` were removed. Create Numbers
with `messaging.quickLinks.create`. Number settings changes use
`sessions.update` with a `revision` and `configuration.set` or
`configuration.reset`. See
[Connect and manage Numbers](https://docs.polymorfa.com/numbers/manage).

The browser `widget.start` and `widget.status` helpers were also removed.

## Webhooks and events

Webhook endpoints and event streams do not have their own API version. Event
payloads follow the current contract. When a field is replaced, Polymorfa
sends the earlier field alongside the new one during the migration window: for
example, native message events carry both `whatsapp_ids` and the earlier
`whatsapp_id`. Read the new field, and make your handler ignore fields and
event types it does not know.

Meta-format webhooks keep Meta's envelope and are not affected by
`Polymorfa-Version`.

## See also

- [API versioning](https://docs.polymorfa.com/api/versioning)
- [Changelog](https://docs.polymorfa.com/changelog)
