Skip to main content
Version: 2026-05

Migrating from 2025-10 to 2026-05

Start with the cross-cutting changes — they affect every call. Then work through the per-resource sections for the resources your integration uses.

Cross-cutting changes​

These changes affect every endpoint regardless of resource.

Request and response envelope​

The flat top-level JSON objects of 2026-05 replace the 2025-10 JSON:API envelope (data.type / data.attributes). Request bodies now send Content-Type: application/json rather than the JSON:API application/vnd.api+json.

Version header​

Update the required AndOpen-API-Version header from 2025-10 to 2026-05. In 2026-05 a missing or unrecognised version is rejected with 400 and an unsupported_api_version error, before the token is checked. See Versioning.

Pagination​

2025-10 paginated lists with a JSON:API links object and an opaque next URL. 2026-05 replaces this with keyset cursors: a list returns a data array and a boolean has_more, and you fetch the next page by passing the id of the last item as the after query parameter. See Pagination for the full model.

Errors​

Both versions return an errors array, but the entries change shape. 2025-10 followed JSON:API: each entry carried status and detail, alongside a top-level jsonapi object. 2026-05 drops the jsonapi object, and each entry now carries type, code, message, and param. The shape is identical across every resource. The full type/code taxonomy and its HTTP-status mapping lives on the Errors page; this section covers only what changed.

Gift requests​

Both gift-request endpoints — Create a gift request and Get a gift request — return the new response shape. Create additionally changes its request body.

Flat response object​

2026-05 returns a gift request as a flat top-level JSON object — read each field directly off the response. This replaces the 2025-10 JSON:API envelope, where the resource sat under data across data.type, data.id, and data.attributes.

// 2026-05
{ "id": "…", "status": "submitted", "redemption_url": "…", "recipient": { … } }

// 2025-10
{ "data": { "type": "gift_requests", "id": "…", "attributes": { "state": "submitted", "redemption_url": "…" } } }

Access fields directly: giftRequest.status in place of giftRequest.data.attributes.state.

state is now status​

The lifecycle field is status, a top-level field — previously state under attributes. The values are unchanged: submitted, redeemed, dispatched, delivered, cancelled.

New response fields: recipient, address, line items, campaign​

The 2026-05 gift request response carries data that 2025-10 omitted entirely. A 2025-10 gift request returned only state (now status), redemption_url, and timestamps — everything below is new.

2026-05 embeds the owned associations — recipient, shipping_address, and line_items — directly as nested objects, so a single read returns the whole gift request. Two are nullable, and the null carries meaning:

  • shipping_address is null for choice-mode gift requests and populated for direct-send ones.
  • line_items is null (never []) until the items are locked — at creation for direct-send, at redemption for choice-mode.

The campaign is referenced by a new campaign_id field (also absent in 2025-10). Fetch the full campaign with Get a campaign.

Create request body​

The create request flattens too, but watch the recipient. 2025-10 wrapped the fields in a data.attributes envelope with the recipient's fields alongside campaign_id; 2026-05 takes a flat body with campaign_id at the top level and the recipient as a nested recipient object.

// 2026-05
{ "campaign_id": "…", "recipient": { "first_name": "…", "last_name": "…", "email": "…" } }

// 2025-10
{ "data": { "type": "gift_requests", "attributes": { "campaign_id": "…", "first_name": "…", "last_name": "…", "email": "…" } } }

See Create a gift request for the full request shape.

Campaigns​

Both campaign endpoints — List campaigns and Get a campaign — change shape in 2026-05: a new response envelope, a different nested-catalogue representation, and a new pagination model on the list.

Flat object, no JSON:API envelope​

In 2025-10 a campaign was a JSON:API resource: data.type ("campaigns"), data.id, and the fields nested under data.attributes. In 2026-05 a campaign is a flat top-level object — id, name, status, and the rest sit at the top level, with no type or attributes wrapper.

state is now status​

The state attribute is renamed to status. Its two public values are unchanged — available and archived.

Catalogue is inline, not in included — and include is gone​

This is the largest change. In 2025-10 the nested catalogue was returned through JSON:API compound documents: the campaign held relationships with resource identifiers, the actual product / variant / stock-level / warehouse records lived in a sibling included array, and you opted into them with the include=products.variants.variant_stock_levels.warehouse query parameter.

In 2026-05 the catalogue is always returned inline and fully nested, with no opt-in:

  • products is an array directly on the campaign.
  • each product carries its variants inline,
  • each variant carries its stock_levels inline (renamed from variant_stock_levels),
  • and each stock level carries its warehouse inline.

Two knock-on renames to watch for: the variant_stock_levels relationship is now the stock_levels array, and a stock level's available count is now quantity.

Because the tree is always inline, the include query parameter no longer exists; remove it from your requests. Which products, variants, and stock levels appear is instead governed by the campaign's fulfilment warehouse — when one is set the catalogue is filtered to it (and each variant exposes a single, warehouse-scoped stock level); campaigns without a warehouse return the catalogue unfiltered. See Get a campaign for the detail.

List pagination​

The campaign list moves to the cursor model described under Pagination above. Two campaigns-specific points: the page is capped at 25 (limit default and maximum 25, because each item carries its full nested catalogue), and the list gains sort and status filter parameters. See List campaigns.

Webhooks​

Webhook deliveries change shape the same way responses do, so update your handler before you point it at 2026-05.

  • Payload. 2025-10 delivered a JSON:API document; 2026-05 delivers a flat JSON object in the same shape the API returns for that resource. Parse it like any other 2026-05 response.
  • Content type. The delivery's Content-Type is now application/json, not application/vnd.api+json.
  • New headers. 2026-05 adds AndOpen-Webhook-Event-Type and AndOpen-Webhook-API-Version, and exposes the event ID as an AndOpen-Webhook-Event-Id header — in 2025-10 it was carried in the payload. The signature and replay-protection scheme is unchanged, so existing verification code keeps working.

See Webhooks for the full payload and verification details.