Offer Transitions

An offer transition describes how a subscription is billed when it moves from one offer to another — an upgrade, a downgrade, or a plan switch within the same product family. It pins a specific from_offer_id → to_offer_id pair to a billing rule (change_charge_behavior) and a toggle (is_active).

Product families already carry a default change-charge behavior for every move inside the family. An offer transition is the fine-grained override: when you need one specific pair to bill differently from the family default, you create a transition for that pair.

Tokeflow orchestrates payments; it does not process or settle funds. Offer transitions are pure catalog modeling — they describe how a plan change should be charged, never who moves the money.

The problem they solve

Most plan changes within a family bill the same way — set that rule once on the family and you're done. But real catalogs have exceptions:

• An upgrade from a monthly to an annual offer should switch immediately (override), while every other move waits for the next renewal.
• A specific downgrade should never prorate, even though the family default prorates.
• You want to temporarily disable billing for one transition pair without touching the rest of the family.

Offer transitions let you encode these exceptions per pair, leaving the family default to handle everything else.

Precedence: explicit transition beats family default

When a subscription moves between two offers, Tokeflow resolves the effective billing rule in this order:

In words:

1. If there is an active transition for the exact from_offer_id → to_offer_id pair and it sets a non-null change_charge_behavior, that value wins.
2. Otherwise — no transition, an inactive transition, or a transition with a null change_charge_behavior — Tokeflow falls back to the product family's default change_charge_behavior.

The change-charge behavior

change_charge_behavior is optional on a transition. Leave it null to inherit the family default for that pair while still using the transition row for its is_active toggle.

The offer transition object

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

Endpoints

POST/api/v1/offer-transitions

Auth: Organization key (with merchant_id) or Merchant key. Requires the offers:write scope.

Creates a transition for a specific offer pair.

curl -X POST https://api.tokeflow.com/api/v1/offer-transitions \
  -H "Authorization: Bearer sk_live_mer_REPLACE_WITH_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3a7f9c2e-2c1d-4a8b-9f10-1e2d3c4b5a6f" \
  -d '{
    "from_offer_id": "ofr_3hk9d2",
    "to_offer_id": "ofr_7pq4m1",
    "change_charge_behavior": "override",
    "is_active": true
  }'

{
  "success": true,
  "data": {
    "id": "oft_a1b2c3d4e5",
    "from_offer_id": "ofr_3hk9d2",
    "to_offer_id": "ofr_7pq4m1",
    "change_charge_behavior": "override",
    "is_active": true,
    "created_at": "2026-05-19T12:00:00.000Z",
    "updated_at": "2026-05-19T12:00:00.000Z"
  },
  "request_id": "req_8f3c1a2b4d5e",
  "timestamp": "2026-05-19T12:00:00.000Z"
}

Common errors:

{
  "error": {
    "type": "conflict_error",
    "code": "OFFER_TRANSITION_ALREADY_EXISTS",
    "message": "A transition for this offer pair already exists.",
    "details": {
      "from_offer_id": "ofr_3hk9d2",
      "to_offer_id": "ofr_7pq4m1"
    },
    "request_id": "req_2b9e7c1f0a3d",
    "timestamp": "2026-05-19T12:00:00.000Z"
  }
}

GET/api/v1/offer-transitions

Auth: Organization key (with merchant_id) or Merchant key. Requires the offers:read scope.

Lists transitions for the merchant. Supports pagination and filtering.

curl "https://api.tokeflow.com/api/v1/offer-transitions?page=1&limit=20&from_offer_id=ofr_3hk9d2&is_active=true" \
  -H "Authorization: Bearer sk_live_mer_REPLACE_WITH_YOUR_KEY"

{
  "success": true,
  "data": [
    {
      "id": "oft_a1b2c3d4e5",
      "from_offer_id": "ofr_3hk9d2",
      "to_offer_id": "ofr_7pq4m1",
      "change_charge_behavior": "override",
      "is_active": true,
      "created_at": "2026-05-19T12:00:00.000Z",
      "updated_at": "2026-05-19T12:00:00.000Z"
    },
    {
      "id": "oft_f6g7h8i9j0",
      "from_offer_id": "ofr_3hk9d2",
      "to_offer_id": "ofr_2zx5n8",
      "change_charge_behavior": null,
      "is_active": true,
      "created_at": "2026-05-19T12:05:00.000Z",
      "updated_at": "2026-05-19T12:05:00.000Z"
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 2,
      "total_pages": 1,
      "has_next": false,
      "has_prev": false
    }
  },
  "request_id": "req_5c1d8e2f9a0b",
  "timestamp": "2026-05-19T12:30:00.000Z"
}

See Pagination & filtering for shared conventions.

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

Auth: Organization key (with merchant_id) or Merchant key. Requires the offers:read scope.

Retrieves a single transition by ID.

curl "https://api.tokeflow.com/api/v1/offer-transitions/oft_a1b2c3d4e5" \
  -H "Authorization: Bearer sk_live_mer_REPLACE_WITH_YOUR_KEY"

{
  "success": true,
  "data": {
    "id": "oft_a1b2c3d4e5",
    "from_offer_id": "ofr_3hk9d2",
    "to_offer_id": "ofr_7pq4m1",
    "change_charge_behavior": "override",
    "is_active": true,
    "created_at": "2026-05-19T12:00:00.000Z",
    "updated_at": "2026-05-19T12:00:00.000Z"
  },
  "request_id": "req_9a0b1c2d3e4f",
  "timestamp": "2026-05-19T12:30:00.000Z"
}

A transition that does not exist or belongs to another merchant returns 404 not_found_error.

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

Auth: Organization key (with merchant_id) or Merchant key. Requires the offers:write scope.

Updates a transition's billing rule or active state. Send only the fields you want to change.

curl -X PATCH https://api.tokeflow.com/api/v1/offer-transitions/oft_a1b2c3d4e5 \
  -H "Authorization: Bearer sk_live_mer_REPLACE_WITH_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "change_charge_behavior": "next_renew",
    "is_active": false
  }'

{
  "success": true,
  "data": {
    "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:00.000Z",
    "updated_at": "2026-05-19T13:15:00.000Z"
  },
  "request_id": "req_0b1c2d3e4f5a",
  "timestamp": "2026-05-19T13:15:00.000Z"
}

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

Auth: Organization key (with merchant_id) or Merchant key. Requires the offers:write scope.

Removes a transition. After deletion, moves between that offer pair fall back to the product-family default. Returns 204 No Content.

curl -X DELETE https://api.tokeflow.com/api/v1/offer-transitions/oft_a1b2c3d4e5 \
  -H "Authorization: Bearer sk_live_mer_REPLACE_WITH_YOUR_KEY"

Related

• Product families — set the default change_charge_behavior that transitions override.
• Offers — and the effective-behavior endpoint, which resolves the value that applies for any pair after precedence.
• Subscriptions — the change-offer endpoint consumes the resolved behavior when a subscriber switches plans.