Merchant offer transitions

An offer transition is a per-pair billing rule for plan changes. It pins one specific from_offer_id → to_offer_id move — an upgrade, a downgrade, or a plan switch within the same product family — to a billing rule (change_charge_behavior) and an on/off toggle (is_active). When a subscription changes between that exact pair of offers, the transition's rule takes precedence over the product family's default.

These endpoints are the surface behind the dashboard's catalog screens: the transitions table, the create dialog, and the activate/deactivate and delete controls. They operate on the same underlying transition rows as the public offer transitions API — a rule created here is immediately visible there, and vice versa.

Every endpoint on this page also requires the x-merchant-id header:

How a transition takes effect

Creating, deactivating, or deleting a transition changes which billing rule applies the next time a subscription moves between the pair:

An inactive or deleted transition never blocks a plan change — the move simply falls back to the product family's default change_charge_behavior. Deactivating (PATCH) is reversible; deleting is not.

The offer transition object

The three change_charge_behavior values:

Dashboard endpoints return the object directly — there is no success/data envelope around single-resource responses.

Endpoints

GET/api/v1/merchant/offer-transitions

Returns a paginated list of the merchant's offer transitions. This is the query behind the dashboard's transitions table, including its offer and status filters.

Query parameters

Example request

curl -G https://api.tokeflow.com/api/v1/merchant/offer-transitions \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs…" \
  -H "x-merchant-id: mrc_123" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=20" \
  --data-urlencode "is_active=true"

Example response — 200 OK

{
  "data": [
    {
      "id": "oft_a1b2c3d4e5",
      "from_offer_id": "ofr_3hk9d2",
      "to_offer_id": "ofr_7pq4m1",
      "change_charge_behavior": "next_renew",
      "is_active": true,
      "created_at": "2026-05-19T12:00:00Z",
      "updated_at": "2026-05-19T12:00:00Z"
    },
    {
      "id": "oft_f6g7h8i9j0",
      "from_offer_id": "ofr_7pq4m1",
      "to_offer_id": "ofr_3hk9d2",
      "change_charge_behavior": null,
      "is_active": true,
      "created_at": "2026-06-02T15:45:00Z",
      "updated_at": "2026-06-02T15:45:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 2,
    "total_pages": 1,
    "has_next": false,
    "has_prev": false
  }
}

The second transition in the example sets change_charge_behavior to null — the row exists for its is_active toggle, and the billing rule falls back to the family default.

Pagination meta

POST/api/v1/merchant/offer-transitions

Creates an offer transition for a from_offer_id → to_offer_id pair. Both offers must belong to the same product family.

Request fields

Example request

curl -X POST https://api.tokeflow.com/api/v1/merchant/offer-transitions \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs…" \
  -H "x-merchant-id: mrc_123" \
  -H "Content-Type: application/json" \
  -d '{
    "from_offer_id": "ofr_3hk9d2",
    "to_offer_id": "ofr_7pq4m1",
    "change_charge_behavior": "next_renew",
    "is_active": true
  }'

Example response — 201 Created

{
  "id": "oft_a1b2c3d4e5",
  "from_offer_id": "ofr_3hk9d2",
  "to_offer_id": "ofr_7pq4m1",
  "change_charge_behavior": "next_renew",
  "is_active": true,
  "created_at": "2026-05-19T12:00:00Z",
  "updated_at": "2026-05-19T12:00:00Z"
}

A 400 is returned when to_offer_id does not belong to the same product family as from_offer_id, or when change_charge_behavior is not one of the three allowed values.

GET/api/v1/merchant/offer-transitions/:id

Retrieves a single offer transition by ID. Returns the offer transition object.

Example request

curl https://api.tokeflow.com/api/v1/merchant/offer-transitions/oft_a1b2c3d4e5 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs…" \
  -H "x-merchant-id: mrc_123"

Example response — 200 OK

{
  "id": "oft_a1b2c3d4e5",
  "from_offer_id": "ofr_3hk9d2",
  "to_offer_id": "ofr_7pq4m1",
  "change_charge_behavior": "next_renew",
  "is_active": true,
  "created_at": "2026-05-19T12:00:00Z",
  "updated_at": "2026-05-19T12:00:00Z"
}

A 404 is returned if the transition does not exist or does not belong to the merchant in x-merchant-id.

PATCH/api/v1/merchant/offer-transitions/:id

Updates an offer transition. The payload is a partial object — send only the fields you want to change. The most common updates are toggling is_active (the dashboard's activate/deactivate control) and adjusting change_charge_behavior, including setting it to null to fall back to the family default.

To repoint a rule at a different offer pair, prefer deleting the transition and creating a new one — the from_offer_id → to_offer_id pair is the transition's identity.

Example request — deactivate a transition

curl -X PATCH https://api.tokeflow.com/api/v1/merchant/offer-transitions/oft_a1b2c3d4e5 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs…" \
  -H "x-merchant-id: mrc_123" \
  -H "Content-Type: application/json" \
  -d '{ "is_active": false }'

Example response — 200 OK

{
  "id": "oft_a1b2c3d4e5",
  "from_offer_id": "ofr_3hk9d2",
  "to_offer_id": "ofr_7pq4m1",
  "change_charge_behavior": "next_renew",
  "is_active": false,
  "created_at": "2026-05-19T12:00:00Z",
  "updated_at": "2026-08-12T09:30:00Z"
}

While is_active is false, the pair bills by the product family's default change_charge_behavior. Re-activate at any time with { "is_active": true }.

DELETE/api/v1/merchant/offer-transitions/:id

Deletes an offer transition. From then on, plan changes between the pair follow the product family's default change_charge_behavior.

Example request

curl -X DELETE https://api.tokeflow.com/api/v1/merchant/offer-transitions/oft_a1b2c3d4e5 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs…" \
  -H "x-merchant-id: mrc_123"

Example response — 204 No Content

The response has no body.

Errors

See Errors for the error format used across the API.

Related

• Offer transitions (public API) — the same resource over sk_ API keys, with the full precedence model.
• Product families — where the default change_charge_behavior lives.
• Offers — the pairs a transition connects, including the effective-behavior resolver.
• Subscriptions — the plan changes these rules govern.