Transiciones de oferta

Una transición de oferta describe cómo se factura una suscripción cuando pasa de una oferta a otra — una mejora, una degradación o un cambio de plan dentro de la misma familia de productos. Fija un par específico from_offer_id → to_offer_id a una regla de facturación (change_charge_behavior) y a un conmutador (is_active).

Las familias de productos ya llevan un comportamiento de cargo por cambio predeterminado para cada traslado dentro de la familia. Una transición de oferta es la anulación de grano fino: cuando necesitas que un par específico se facture de forma distinta al valor predeterminado de la familia, creas una transición para ese par.

Tokeflow orquesta pagos; no procesa ni liquida fondos. Las transiciones de oferta son pura modelización de catálogo — describen cómo debe cobrarse un cambio de plan, nunca quién mueve el dinero.

El problema que resuelven

La mayoría de los cambios de plan dentro de una familia se facturan de la misma manera — establece esa regla una vez en la familia y listo. Pero los catálogos reales tienen excepciones:

• Una mejora de una oferta mensual a una anual debería cambiar de inmediato (override), mientras que cualquier otro traslado espera a la siguiente renovación.
• Una degradación específica nunca debería prorratearse, aunque el valor predeterminado de la familia sí prorratee.
• Quieres deshabilitar temporalmente la facturación de un par de transición sin tocar el resto de la familia.

Las transiciones de oferta te permiten codificar estas excepciones por par, dejando que el valor predeterminado de la familia se ocupe de todo lo demás.

Precedencia: la transición explícita gana al valor predeterminado de la familia

Cuando una suscripción se traslada entre dos ofertas, Tokeflow resuelve la regla de facturación efectiva en este orden:

En palabras:

1. Si existe una transición activa para el par exacto from_offer_id → to_offer_id y define un change_charge_behavior no nulo, ese valor gana.
2. En caso contrario — sin transición, una transición inactiva o una transición con un change_charge_behavior nulo — Tokeflow recurre al change_charge_behavior predeterminado de la familia de productos.

El comportamiento de cargo por cambio

change_charge_behavior es opcional en una transición. Déjalo en null para heredar el valor predeterminado de la familia para ese par mientras sigues usando la fila de la transición para su conmutador is_active.

El objeto de transición de oferta

{
  "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: clave de Organization (con merchant_id) o clave de Merchant. Requiere el ámbito offers:write.

Crea una transición para un par de ofertas específico.

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"
}

Errores comunes:

{
  "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: clave de Organization (con merchant_id) o clave de Merchant. Requiere el ámbito offers:read.

Lista las transiciones del merchant. Admite paginación y filtrado.

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"
}

Consulta Paginación y filtrado para conocer las convenciones compartidas.

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

Auth: clave de Organization (con merchant_id) o clave de Merchant. Requiere el ámbito offers:read.

Recupera una única transición por 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"
}

Una transición que no existe o pertenece a otro merchant devuelve 404 not_found_error.

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

Auth: clave de Organization (con merchant_id) o clave de Merchant. Requiere el ámbito offers:write.

Actualiza la regla de facturación o el estado activo de una transición. Envía solo los campos que quieras cambiar.

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: clave de Organization (con merchant_id) o clave de Merchant. Requiere el ámbito offers:write.

Elimina una transición. Tras la eliminación, los traslados entre ese par de ofertas recurren al valor predeterminado de la familia de productos. Devuelve 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"

Relacionado

• Familias de productos — establece el change_charge_behavior predeterminado que anulan las transiciones.
• Ofertas — y el endpoint effective-behavior, que resuelve el valor que se aplica para cualquier par tras la precedencia.
• Suscripciones — el endpoint change-offer consume el comportamiento resuelto cuando un suscriptor cambia de plan.