Source: https://dinakar-pageloop-knowledge-base.docs-staging.pageloop.ai/guides/migrating-to-v2

# Migrating to v2

# Migrating to v2

The `2026-06-01` API version is the first to be called v2. It is not a rewrite — most
integrations need two or three changes.

> [!INFO]
>
> Your API version is pinned per key, so you can migrate one service at a time. Create a
> new key pinned to `2026-06-01`, migrate the caller, then retire the old key.

## Breaking changes

#### Amounts are integers, not decimal strings

`payload.amount` was a decimal string (`"49.00"`). It is now `payload.amountCents`, an
integer number of minor units (`4900`).

```diff
- const dollars = parseFloat(event.payload.amount);
+ const dollars = event.payload.amountCents / 100;
```

#### The signature header dropped v0

v1 signatures were introduced alongside `v0` in 2025 and both were sent during the
overlap. `2026-06-01` sends only `v1=`. If you parse the header positionally rather than
by key, fix that first.

#### Empty payloads are rejected

`payload` must now be a non-empty JSON object. Publishing `{}` returns
`422 empty_payload`. Previously it was accepted and delivered as-is.

## Non-breaking additions

- `streamKey` — opt-in ordering. Absent means unordered, exactly as before.
- `apiVersion` on the event body, so a consumer can tell which shape it is reading.
- `GET /v1/deliveries` accepts `status` and `since` filters.

## Migration checklist

1. **Create a v2 key**

   **Settings → API keys → Create key**, pinned to `2026-06-01`.
2. **Update the amount field**

   Search your handlers for `payload.amount` and switch to `amountCents`.
3. **Parse the signature header by key**

   Split on `,` then on `=`, and look up `v1` by name.
4. **Cut over and verify**

   Deploy, then watch `exhausted` on the metrics endpoint for an hour.

## Support window

> [!WARNING]
>
> The `2025-11-01` version is supported until **1 March 2027**. After that, keys pinned to
> it will receive `410 api_version_retired`.

See the [Changelog](/reference/changelog) for the full version history.