Offers

Un offer es una configuración adquirible de un producto. El producto modela qué vendes; el offer modela cómo se adquiere y se factura: el ciclo de facturación, el periodo de prueba, el límite de ciclos y uno o más precios — uno por moneda.

Un único producto puede tener muchos offers. Un plan mensual y un plan anual del mismo producto son dos offers. Una promoción y el precio estándar son dos offers. Esta separación te permite lanzar nuevos precios, ejecutar experimentos y localizar importes sin tocar el producto en sí.

Cómo se facturan los offers

El billing_cycle de un offer define su cadencia:

El cycle_limit limita el número de cargos. Omítelo (o establécelo en null) para cobrar hasta que se cancele la suscripción. Cuando se alcanza el límite, la suscripción expira — a menos que renew_after_cycle_limit sea true, en cuyo caso se crea una nueva suscripción. Si renewal_offer_id está definido, se usa ese offer para la renovación posterior al límite; de lo contrario, se renueva con el mismo offer.

Importe del primer cargo

Cada precio lleva un amount base y un first_charge_amount opcional. El first_charge_amount se aplica cuando el setup_charge del offer es true, y establece el precio del primer ciclo de facturación — útil para un precio de introducción, una tarifa única de configuración o un primer mes con descuento. Un first_charge_amount de 0 significa un cargo de validación de tarjeta (verificar el instrumento sin cobrar).

Un periodo de prueba gratuito anula todo esto: consulta la sección Periodo de prueba gratuito más abajo.

Periodo de prueba gratuito

Cuando free_trial es true, trial_days es obligatorio y define la duración del periodo de prueba en días. Durante el periodo de prueba no se realiza ningún cargo recurrente; la facturación comienza cuando termina el periodo de prueba.

Un periodo de prueba cobra 0 al inicio, y setup_charge no es obligatorio. La regla de precio lee free_trial directamente, así que el primer cobro es 0 tenga o no el offer un cargo de configuración. La tarjeta se sigue registrando — el checkout de importe cero ejecuta una validación de tarjeta — para que el primer cobro real pueda realizarse al terminar el periodo de prueba.

Lo único que setup_charge todavía añade a un periodo de prueba es un precio de adquisición: con setup_charge: true y un first_charge_amount mayor que 0, ese importe se cobra al inicio como tarifa de alta, y el periodo de prueba cubre el primer ciclo con normalidad. Fijarlo igual o por encima de amount no es un periodo de prueba — el cliente ya pagó el primer ciclo, así que la suscripción empieza activa en lugar de en prueba.

El objeto offer

{
  "id": "ofr_a1b2c3d4e5",
  "product_id": "prd_a1b2c3d4e5",
  "name": "Mensal",
  "slug": "mensal",
  "description": "Plano mensal padrão",
  "billing_cycle": "monthly",
  "custom_billing_days": null,
  "cycle_limit": 12,
  "free_trial": false,
  "trial_days": null,
  "setup_charge": true,
  "renew_after_cycle_limit": false,
  "renewal_offer_id": null,
  "is_default": true,
  "status": "active",
  "created_at": "2026-01-15T12:30:00.000Z",
  "updated_at": "2026-01-15T12:30:00.000Z",
  "prices": [
    {
      "id": "opr_b1c2d3e4f5",
      "offer_id": "ofr_a1b2c3d4e5",
      "currency": "BRL",
      "amount": 9900,
      "first_charge_amount": 0,
      "is_default": true,
      "created_at": "2026-01-15T12:30:00.000Z",
      "updated_at": "2026-01-15T12:30:00.000Z"
    },
    {
      "id": "opr_c2d3e4f5g6",
      "offer_id": "ofr_a1b2c3d4e5",
      "currency": "USD",
      "amount": 1900,
      "first_charge_amount": null,
      "is_default": false,
      "created_at": "2026-01-15T12:30:00.000Z",
      "updated_at": "2026-01-15T12:30:00.000Z"
    }
  ]
}

Atributos

El objeto precio del offer

Endpoints

Todos los endpoints de offers están bajo https://api.tokeflow.com/api/v1. Consulta Autenticación para claves y scopes. Los offers son un recurso con alcance de merchant: con una clave de Organization debes identificar el merchant de destino mediante merchant_id; con una clave de Merchant el merchant se infiere.

POST/api/v1/offers

Crea un offer junto con al menos un precio.

Auth: clave de Organization (con merchant_id) o clave de Merchant. Scope: offers:write.

Cada entrada en prices:

curl -X POST https://api.tokeflow.com/api/v1/offers \
  -H "Authorization: Bearer sk_live_mer_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8f3c1d2a-7b6e-4c0a-9f12-3d4e5f6a7b8c" \
  -d '{
    "product_id": "prd_a1b2c3d4e5",
    "name": "Mensal",
    "slug": "mensal",
    "billing_cycle": "monthly",
    "status": "active",
    "setup_charge": true,
    "is_default": true,
    "prices": [
      { "currency": "BRL", "amount": 9900, "first_charge_amount": 0, "is_default": true },
      { "currency": "USD", "amount": 1900, "is_default": false }
    ]
  }'

Respuesta 201 Created:

{
  "success": true,
  "data": {
    "id": "ofr_a1b2c3d4e5",
    "product_id": "prd_a1b2c3d4e5",
    "name": "Mensal",
    "slug": "mensal",
    "description": null,
    "billing_cycle": "monthly",
    "custom_billing_days": null,
    "cycle_limit": null,
    "free_trial": false,
    "trial_days": null,
    "setup_charge": true,
    "renew_after_cycle_limit": false,
    "renewal_offer_id": null,
    "is_default": true,
    "status": "active",
    "created_at": "2026-01-15T12:30:00.000Z",
    "updated_at": "2026-01-15T12:30:00.000Z",
    "prices": [
      {
        "id": "opr_b1c2d3e4f5",
        "offer_id": "ofr_a1b2c3d4e5",
        "currency": "BRL",
        "amount": 9900,
        "first_charge_amount": 0,
        "is_default": true,
        "created_at": "2026-01-15T12:30:00.000Z",
        "updated_at": "2026-01-15T12:30:00.000Z"
      },
      {
        "id": "opr_c2d3e4f5g6",
        "offer_id": "ofr_a1b2c3d4e5",
        "currency": "USD",
        "amount": 1900,
        "first_charge_amount": null,
        "is_default": false,
        "created_at": "2026-01-15T12:30:00.000Z",
        "updated_at": "2026-01-15T12:30:00.000Z"
      }
    ]
  },
  "request_id": "req_8f3c2a1b",
  "timestamp": "2026-01-15T12:30:00.000Z"
}

GET/api/v1/offers

Lista los offers con paginación y filtros.

Auth: clave de Organization (con merchant_id) o clave de Merchant. Scope: offers:read.

curl "https://api.tokeflow.com/api/v1/offers?product_id=prd_a1b2c3d4e5&status=active&limit=20" \
  -H "Authorization: Bearer sk_live_mer_xxx"

Respuesta 200 OK:

{
  "success": true,
  "data": [
    {
      "id": "ofr_a1b2c3d4e5",
      "product_id": "prd_a1b2c3d4e5",
      "name": "Mensal",
      "slug": "mensal",
      "description": null,
      "billing_cycle": "monthly",
      "custom_billing_days": null,
      "cycle_limit": null,
      "free_trial": false,
      "trial_days": null,
      "setup_charge": true,
      "renew_after_cycle_limit": false,
      "renewal_offer_id": null,
      "is_default": true,
      "status": "active",
      "created_at": "2026-01-15T12:30:00.000Z",
      "updated_at": "2026-01-15T12:30:00.000Z"
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 1,
      "total_pages": 1,
      "has_next": false,
      "has_prev": false
    }
  },
  "request_id": "req_8f3c2a1c",
  "timestamp": "2026-01-15T12:30:00.000Z"
}

GET/api/v1/offers/:id

Recupera un único offer, incluidos sus precios.

Auth: clave de Organization (con merchant_id) o clave de Merchant. Scope: offers:read.

curl https://api.tokeflow.com/api/v1/offers/ofr_a1b2c3d4e5 \
  -H "Authorization: Bearer sk_live_mer_xxx"

La respuesta 200 OK devuelve el objeto offer (con prices) envuelto en el sobre de éxito estándar. Se devuelve un 404 (not_found_error) si el offer no existe o pertenece a otro merchant.

PATCH/api/v1/offers/:id

Actualiza los campos mutables de un offer. Envía solo los campos que quieras cambiar.

Auth: clave de Organization (con merchant_id) o clave de Merchant. Scope: offers:write.

curl -X PATCH https://api.tokeflow.com/api/v1/offers/ofr_a1b2c3d4e5 \
  -H "Authorization: Bearer sk_live_mer_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Mensal Promo", "cycle_limit": 12 }'

La respuesta 200 OK devuelve el objeto offer actualizado.

DELETE/api/v1/offers/:id

Elimina de forma lógica (soft-delete) un offer. La eliminación se propaga en cascada a los precios del offer. Los offers eliminados de forma lógica se pueden recuperar con restore.

Auth: clave de Organization (con merchant_id) o clave de Merchant. Scope: offers:write.

curl -X DELETE https://api.tokeflow.com/api/v1/offers/ofr_a1b2c3d4e5 \
  -H "Authorization: Bearer sk_live_mer_xxx"

Respuesta: 204 No Content (cuerpo vacío).

GET/api/v1/offers/:id/default-price

Resuelve el precio predeterminado de un offer. Pasa currency para obtener el precio predeterminado en esa moneda; la respuesta es null si no existe un precio coincidente.

Auth: clave de Organization (con merchant_id) o clave de Merchant. Scope: offers:read.

curl "https://api.tokeflow.com/api/v1/offers/ofr_a1b2c3d4e5/default-price?currency=BRL" \
  -H "Authorization: Bearer sk_live_mer_xxx"

Respuesta 200 OK:

{
  "success": true,
  "data": {
    "id": "opr_b1c2d3e4f5",
    "offer_id": "ofr_a1b2c3d4e5",
    "currency": "BRL",
    "amount": 9900,
    "first_charge_amount": 0,
    "is_default": true,
    "created_at": "2026-01-15T12:30:00.000Z",
    "updated_at": "2026-01-15T12:30:00.000Z"
  },
  "request_id": "req_8f3c2a1d",
  "timestamp": "2026-01-15T12:30:00.000Z"
}

Cuando no coincide ningún precio predeterminado, data es null.

GET/api/v1/offers/:fromId/transitions/:toId/effective-behavior

Resuelve el change_charge_behavior efectivo para mover una suscripción de un offer a otro — por ejemplo, una mejora o una degradación. Ambos offers deben pertenecer a la misma familia de productos.

Orden de resolución:

1. Si existe una transición activa para el par fromId → toId y establece un change_charge_behavior, ese valor prevalece.
2. De lo contrario, se aplica el valor predeterminado de la familia de productos del offer de origen.

Auth: clave de Organization (con merchant_id) o clave de Merchant. Scope: offers:read.

curl "https://api.tokeflow.com/api/v1/offers/ofr_from123/transitions/ofr_to456/effective-behavior" \
  -H "Authorization: Bearer sk_live_mer_xxx"

Respuesta 200 OK:

{
  "success": true,
  "data": {
    "change_charge_behavior": "next_renew"
  },
  "request_id": "req_8f3c2a1e",
  "timestamp": "2026-01-15T12:30:00.000Z"
}

POST/api/v1/offers/:id/restore

Restaura un offer eliminado de forma lógica y sus precios.

Auth: clave de Organization (con merchant_id) o clave de Merchant. Scope: offers:write.

curl -X POST https://api.tokeflow.com/api/v1/offers/ofr_a1b2c3d4e5/restore \
  -H "Authorization: Bearer sk_live_mer_xxx"

La respuesta devuelve el objeto offer restaurado.

POST/api/v1/offers/:id/archive

Archiva un offer (establece status en archived). Los offers archivados permanecen en el catálogo y siguen siendo recuperables, pero no deberían ofrecerse para nuevas compras.

Auth: clave de Organization (con merchant_id) o clave de Merchant. Scope: offers:write.

curl -X POST https://api.tokeflow.com/api/v1/offers/ofr_a1b2c3d4e5/archive \
  -H "Authorization: Bearer sk_live_mer_xxx"

La respuesta devuelve el offer con status: "archived".

POST/api/v1/offers/:id/unarchive

Desarchiva un offer (vuelve a establecer status en active).

Auth: clave de Organization (con merchant_id) o clave de Merchant. Scope: offers:write.

curl -X POST https://api.tokeflow.com/api/v1/offers/ofr_a1b2c3d4e5/unarchive \
  -H "Authorization: Bearer sk_live_mer_xxx"

La respuesta devuelve el offer con status: "active".

Errores

Los endpoints de offers usan el sobre de error estándar. Casos comunes:

Relacionados

• Products — aquello a lo que un offer pone precio.
• Offer Prices — gestiona precios por moneda en un offer.
• Offer Transitions — anula el comportamiento de cambio entre pares de offers.
• Product Families — agrupa productos y establece el comportamiento de cambio predeterminado.