Suscripciones

Conceptos previos

Antes de integrar las suscripciones ten en cuenta:

  • Ambiente (test / producción): el token de acceso define el ambiente. Un token de pruebas (api-access:test) solo puede leer y crear datos de pruebas; un token de producción (api-access:production) solo opera sobre datos de producción. Las lecturas quedan filtradas automáticamente por el ambiente del token.
  • Nombres alternativos: además de los nombres históricos (group, plan, subscriber) puedes usar los alias product, price y customer, que apuntan a los mismos recursos. Ejemplo: GET /api/v1/subscriptions/customer equivale a GET /api/v1/subscriptions/subscriber.
  • Descuentos: los descuentos ahora se gestionan con Cupones reutilizables (porcentaje o monto fijo). Los campos discount_* del plan se mantienen por compatibilidad pero se recomienda usar cupones.

Idempotencia (Idempotency-Key)

Todas las escrituras (POST/PUT/DELETE) de subscriptions/* aceptan el header Idempotency-Key. Si repites una solicitud con la misma key y los mismos parámetros, se reproduce la respuesta original (con el header Idempotency-Replayed: true) sin volver a ejecutar el cobro o la creación. Es la forma segura de reintentar ante errores de red.

curl -X POST "/api/v1/subscriptions/subscription" \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-type: application/json' \
  -H 'Idempotency-Key: 9b1f0e34-6b2a-4a7e-9d0a-unico-por-operacion' \
  -d '{ "plan_id": "...", "subscriber_id": "...", "card": "...", "office": 1 }'

{warning} Si reutilizas la misma Idempotency-Key con parámetros distintos recibirás un error 409.

Objetos expandibles (expand)

Al consultar una suscripción puedes incrustar relaciones con expand[] y así evitar llamadas adicionales. Valores soportados: plan, subscriber, next_transaction.

curl -X GET "/api/v1/subscriptions/subscription/your-subscription-id?expand[]=plan&expand[]=subscriber" \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-type: application/json'

Estados de una suscripción

El campo status (presente en las respuestas de suscripción) refleja el estado actual de la suscripción:

status Significado
trial En período de prueba.
activa Activa y al día.
en_gracia Un cobro falló pero sigue dentro del período de gracia (past due).
pausada Cobros pausados (ver Pause).
cancelada Cancelada; activa hasta el fin del período vigente.
finalizada Terminada; no se realizarán más cobros.

Dos formatos de respuesta

Esta página tiene una peculiaridad que conviene conocer antes de escribir el parser:

Qué llamas Qué recibes
Las consultas (GET) snake_case: subscription_plan_id, next_transaction, trial_ends_at, is_active…
Las acciones (cancelar, pausar, reanudar, cambiar de plan) camelCase: planId, nextRenewAt, isActive, onGracePeriod…

No son los mismos campos con otro nombre: son dos representaciones distintas de la suscripción. No reutilices el parser de una para la otra. Cada sección de abajo muestra la que le corresponde.

{info} La fuente de verdad siempre es un GET a la suscripción. Si después de una acción necesitas el objeto completo y consistente, vuelve a consultarla.

Listar suscripciones

Descripción: Devuelve la lista paginada de todas tus suscripciones (filtradas por el ambiente del token: pruebas o producción). Útil para tableros, sincronizaciones y reconciliación.

GET /api/v1/subscriptions/subscription

Filtros

Todos son opcionales y se combinan entre sí. Sin ninguno, la respuesta es la lista completa del ambiente del token.

Parámetro Tipo Qué hace
filter[subscriber_id] UUID exacto Todas las suscripciones de un suscriptor
filter[plan_id] UUID exacto Todas las de un plan
filter[status] exacto trial, activa, en_gracia, pausada, cancelada, finalizada
filter[email] parcial Por el correo del suscriptor
filter[subscription_id] parcial Por el id de la suscripción
filter[description] parcial Por la descripción que guardaste al crearla
filter[plan_name] parcial Por el nombre del plan
filter[active] 1, 0, all Si está dando servicio ahora mismo
filter[start_date] fecha Creadas desde esa fecha (inclusive)
filter[finish_date] fecha Creadas hasta esa fecha (inclusive)
sort campo created_at, starts_at, ends_at, trial_ends_at. Prefija con - para descendente 
curl -X GET \
'https://sag-qa.efipay.co/api/v1/subscriptions/subscription?filter[email]=ana@correo.com&filter[status]=activa' \
-H 'Authorization: Bearer TU_TOKEN' \
-H 'Accept: application/json'

{success} Para reconciliar después de un fallo tuyo. Si tu sistema se cayó justo después de crear una suscripción y no sabes si quedó registrada, búscala por filter[subscriber_id] o filter[email] y compara created_at. No hace falta que tengas el id que nunca alcanzaste a guardar.

{info} ¿Referencia externa? Todavía no hay un campo external_reference. Mientras tanto, usa description (hasta 255 caracteres) para guardar tu propio identificador al crear la suscripción: es filtrable con filter[description].

Obtener una suscripción

Descripción: Devuelve el detalle de una suscripción a partir de su id. Acepta objetos expandibles para incluir el plan, el suscriptor o el próximo cobro.

{success} Respuesta satisfactoria code: 200

{
"id": "9da5903d-3d1a-4f60-b487-b6b6cd7d9d1b",
"description": null,
"webhook_url": "https://tu-comercio.com/webhook",
"trial_ends_at": "2026-07-15 00:00:00",
"discount_ends_at": null,
"starts_at": "2026-07-15 00:00:00",
"ends_at": "2026-08-15 00:00:00",
"grace_ends_at": "2026-08-18 00:00:00",
"next_transaction": "2026-08-15",
"canceled_at": null,
"paused_at": null,
"resumes_at": null,
"environment": "production",
"status": "activa",
"on_trial": false,
"on_discount": false,
"on_grace_period": false,
"paused": false,
"canceled": false,
"is_active": true,
"is_ended": false,
"subscription_plan_id": "9a4698e5-d936-4298-84dc-4a770bfacc19",
"subscriber_id": "9a469901-d010-4afe-94fe-da6790a4f72b",
"office_id": "9a3bf0a4-9854-418f-aa05-5a04b8ce4372",
"created_at": "2026-07-01 09:12:00",
"updated_at": "2026-07-15T00:00:00.000000Z"
}

Campos y tipos

Campo Tipo Descripción
id uuid Id de la suscripción
description string | null Texto libre tuyo, hasta 255 caracteres
webhook_url string | null Dónde te avisamos los cambios
status string trial, activa, en_gracia, pausada, cancelada, finalizada
environment string production o testing
starts_at fecha | null Inicio del período vigente
ends_at fecha | null Fin del período vigente. Hasta aquí hay servicio
grace_ends_at fecha | null Fin de la ventana de gracia para reintentar el cobro
trial_ends_at fecha | null Fin de la prueba
discount_ends_at fecha | null Fin del descuento
canceled_at fecha | null Cuándo se canceló. Con at_period_end: false es igual a ends_at
paused_at fecha | null Cuándo se pausaron los cobros
resumes_at fecha | null Cuándo se reanudan. null con paused_at = pausa indefinida
next_transaction fecha | null Fecha del próximo cobro programado
on_trial bool En período de prueba
on_discount bool Con descuento vigente
on_grace_period bool Dentro de la gracia: el cobro falló pero sigue habiendo servicio
paused bool Cobros pausados ahora mismo
canceled bool Cancelada. Puede ser true con is_active en true
is_active bool Si hay servicio ahora mismo. Es el que debes mirar para dar o cortar acceso
is_ended bool El período terminó
subscription_plan_id uuid Plan
subscriber_id uuid Suscriptor
office_id — Sede
created_at / updated_at fecha

{warning} canceled e is_active no son opuestos. Una suscripción cancelada al final del período tiene canceled: true e is_active: true hasta ends_at. Para decidir si el cliente tiene acceso, mira is_active.

{info} Las fechas van en hora de Colombia con formato Y-m-d H:i:s. Los campos plan, subscriber y next_transaction_charge solo aparecen si los pides con expand[].

Suscripciones de un plan

Descripción: Lista las suscripciones asociadas a un plan específico. Útil para saber cuántos clientes están suscritos a un plan.

Suscripciones de un suscriptor

Descripción: Lista las suscripciones de un suscriptor (cliente) específico.

Crear una suscripción

Descripción: Crea una suscripción a partir de un plan y un suscriptor ya creados, más los datos de la tarjeta con la que se cobrará la recurrencia. La tarjeta se tokeniza de forma segura; si prefieres, puedes enviar un card (token ya generado en Tokenizado) y usaremos ese token para los cobros. El primer cobro se realiza al momento (o al terminar el período de prueba, si el plan lo tiene).

La tarjeta puede llegar de dos maneras excluyentes: como card (un token ya generado en Tokenizado) o como el objeto card_information con los datos en claro. Envía una u otra, nunca las dos.

Nombre del campo Descripción Reglas
plan_id Id del plan a cobrar. Debe estar activo y pertenecer a la misma sucursal que envías en office ['required', 'exists:subscription_plans,id']
subscriber_id Id del suscriptor. Debe pertenecer a la misma sucursal que envías en office ['required', 'exists:subscribers,id']
office Sucursal de la suscripción. Debe ser una de tus sucursales ['required', 'exists:offices,id']
description Descripción libre de esta suscripción ['nullable', 'string', 'max:255']
webhook_url URL a la que notificaremos cada cobro de esta suscripción. Recibe un POST firmado con la cabecera Signature. Ver webhooks ['nullable', 'url']
card Token de una tarjeta guardada. Si lo envías, no envíes card_information ['required_without:card_information', 'missing_with:card_information', 'string']
card_information.holder Nombre impreso en la tarjeta ['sometimes', 'required', 'missing_with:card', 'string', 'max:80']
card_information.number Número de la tarjeta, sin espacios. Se valida como número de tarjeta real ['sometimes', 'required', 'missing_with:card', 'numeric']
card_information.datetime Vencimiento en formato YYYY-MM, con mes entre 01 y 12. No puede estar vencida ['sometimes', 'required', 'missing_with:card', 'date_format:Y-m', 'after_or_equal:<mes actual>']
card_information.cvv Código de seguridad. La cantidad de dígitos se valida según la franquicia que resulte de card_information.number ['sometimes', 'required', 'missing_with:card', 'numeric']

Solicitud con token

curl -X POST\
"/api/v1/subscriptions/subscription"\
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H "Content-type: application/json" \
-d '{
    "plan_id": "9a9331d9-ea9a-4ad4-a9a4-0d23bd91fff1",
    "subscriber_id": "9a933275-1573-497c-916c-ba7fe4f99326",
    "card": "your-token-card-here",
    "office": 1
}'

Ejemplo de solicitud sin token:

curl -X POST\
"/api/v1/subscriptions/subscription"\
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H "Content-type: application/json" \
-d '{
    "plan_id": "9a9331d9-ea9a-4ad4-a9a4-0d23bd91fff1",
    "subscriber_id": "9a933275-1573-497c-916c-ba7fe4f99326",
    "card_information": {
        "holder": "Holder Holder",
        "number": "5249314023340339",
        "datetime": "2026-02",
        "cvv": 899
    },
    "office": 1
}'

Cancelar suscripción

Descripción: Cancela una suscripción activa. Por defecto la cancelación es al final del período vigente: el cliente conserva el servicio hasta ends_at.

Cuándo surte efecto

Cuerpo canceled_at ends_at is_active Qué significa
(vacío) o {"at_period_end": true} Ahora No cambia true hasta ends_at El cliente ya pagó el ciclo: lo termina
{"at_period_end": false} Ahora Ahora false de inmediato Corte inmediato, también de la gracia 
curl -X PUT \
'https://sag-qa.efipay.co/api/v1/subscriptions/subscription/cancel/your-subscription-id' \
-H 'Authorization: Bearer TU_TOKEN' \
-H 'Content-type: application/json' \
-d '{ "at_period_end": false }'

{info} No llega un renew después de cancelar. En cuanto queda registrada la cancelación, el motor de cobro deja de considerar la suscripción: no hay más cobros ni más reintentos pendientes. El último evento que recibes es canceled.

{warning} at_period_end: false no devuelve dinero. Corta el servicio, no reembolsa el ciclo ya cobrado. Para eso está la devolución.

{success} Respuesta satisfactoria code: 200

{
"canceled": true,
"at_period_end": true,
"subscription": {
"id": "9da5903d-3d1a-4f60-b487-b6b6cd7d9d1b",
"status": "cancelada",
"canceled": true
}
}

{danger} La suscripción ya estaba cancelada code: 400

{
"canceled": false,
"message": "La suscripción ya está cancelada."
}

Pausar cobros

Descripción: Pausa los cobros de una suscripción. Mientras esté pausada, el motor de recurrencia no realiza cobros. Puedes programar una reanudación automática con resumes_at; si no lo envías, queda pausada hasta que llames a Reanudar cobros.

Nombre del campo Descripción Reglas
resumes_at Fecha y hora en que la suscripción se reanuda sola. Debe ser futura. Si la omites, la pausa dura hasta que llames a reanudar ['sometimes', 'nullable', 'date', 'after:now'] 

curl -X POST\
"/api/v1/subscriptions/subscription/9da5903d-3d1a-4f60-b487-b6b6cd7d9d1b/pause"\
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H "Content-type: application/json" \
-d '{ "resumes_at": "2026-09-01 00:00:00" }'

{success} Respuesta satisfactoria code: 200

{
"paused": true,
"subscription": {
"id": "9da5903d-3d1a-4f60-b487-b6b6cd7d9d1b",
"status": "pausada",
"paused": true,
"pausedAt": "2026-07-30 10:00:00",
"resumesAt": "2026-09-01 00:00:00"
}
}

{danger} No se puede pausar code: 400

{
"paused": false,
"message": "No se puede pausar una suscripción cancelada."
}

Reanudar cobros

Descripción: Reanuda los cobros de una suscripción pausada.

curl -X POST\
"/api/v1/subscriptions/subscription/9da5903d-3d1a-4f60-b487-b6b6cd7d9d1b/resume"\
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H "Content-type: application/json"

{success} Respuesta satisfactoria code: 200

{
"resumed": true,
"subscription": {
"id": "9da5903d-3d1a-4f60-b487-b6b6cd7d9d1b",
"status": "activa",
"paused": false
}
}

Actualizar método de pago (tarjeta)

Descripción: Actualiza la tarjeta con la que se cobran las recurrencias de una suscripción. La tarjeta se tokeniza de forma segura y reemplaza a la anterior.

Nombre del campo Descripción Reglas
number Número de la nueva tarjeta, sin espacios. Se valida como número de tarjeta real ['required', 'numeric']
datetime Vencimiento en formato YYYY-MM (por ejemplo 2030-05). No puede estar vencida ['required', 'date']
cvv Código de seguridad. La cantidad de dígitos se valida según la franquicia que resulte de number ['required', 'numeric'] 

curl -X PUT\
"/api/v1/subscriptions/subscription/9da5903d-3d1a-4f60-b487-b6b6cd7d9d1b/update-payment-method"\
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H "Content-type: application/json" \
-d '{
    "number": "5249314023340339",
    "datetime": "2028-05",
    "cvv": 899
}'

{success} Respuesta satisfactoria code: 200

{ "updated": true }

{danger} Suscripción cancelada code: 400

{ "message": "No se puede actualizar el método de pago de una suscripción cancelada" }

Renovar suscripción

POST /api/v1/subscriptions/subscription/{subscription-id}/renew

Descripción: Le envía al suscriptor una invitación de renovación por correo, con un enlace en el que confirma que quiere seguir. Sirve para reactivar una suscripción que ya terminó.

{danger} No cobra nada. Este endpoint no genera un cobro inmediato ni reactiva la suscripción por sí solo: solo manda el correo. El cobro ocurre cuando el suscriptor acepta la invitación. La invitación vence a los 7 días y solo puede haber una pendiente por suscripción.

Si lo que quieres es cobrar ya mismo, crea una suscripción nueva o usa un cobro puntual.

No recibe cuerpo. El suscriptor debe tener una tarjeta guardada, porque la invitación la reutiliza.

curl -X POST \
'/api/v1/subscriptions/subscription/9da5903d-3d1a-4f60-b487-b6b6cd7d9d1b/renew' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Accept: application/json'

{success} Invitación enviada code: 200

{
"renewed": true,
"message": "Se ha enviado una invitación de renovación al suscriptor por correo electrónico."
}

{danger} Ya hay una invitación pendiente code: 400

{
"renewed": false,
"message": "Ya existe una invitación de renovación pendiente para esta suscripción."
}

{danger} El suscriptor no tiene tarjeta guardada code: 400

{
"renewed": false,
"message": "El suscriptor no tiene una tarjeta guardada. No se puede enviar la invitación."
}

Cambiar de plan (con prorrateo)

Descripción: Cambia el plan de una suscripción de forma inmediata y con prorrateo. No requiere que el suscriptor acepte nada.

El prorrateo calcula:

  • Un crédito por el tiempo no usado del plan actual.
  • Un cargo por el tiempo restante del período con el nuevo plan.
  • El neto (net): si es positivo se genera un cobro inmediato (upgrade); si es negativo, ese monto queda como crédito a favor en el balance del cliente (downgrade).

El cobro pendiente del próximo ciclo se re-tarifica automáticamente al precio del nuevo plan.

{info} Usa primero ChangePlanPreview para mostrarle al cliente el prorrateo antes de confirmar.

Nombre del campo Descripción Reglas
plan_id Id del nuevo plan. Debe estar activo, ser de tu comercio y del mismo ambiente que la suscripción ['required', 'exists:subscription_plans,id']
mode direct (por defecto) aplica el cambio de inmediato. invitation le envía al suscriptor una invitación por correo para que lo apruebe ['sometimes', 'in:direct,invitation']
proration_behavior Qué hacer con el tiempo ya pagado: create_prorations (por defecto), none sin prorrateo, always_invoice factura el ajuste de inmediato ['sometimes', 'in:create_prorations,none,always_invoice'] 

curl -X PUT\
"/api/v1/subscriptions/subscription/9da5903d-3d1a-4f60-b487-b6b6cd7d9d1b/change-plan"\
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H "Content-type: application/json" \
-d '{
    "plan_id": "9a4698e5-d936-4298-84dc-4a770bfacc19"
}'

{success} Cambio directo aplicado (upgrade con cobro de prorrateo) code: 200

{
"changed": true,
"proration": {
"currency": "COP",
"unused_fraction": 0.6,
"credit_unused": 6000,
"charge_new": 18000,
"net": 12000,
"line_items": [
{ "description": "Tiempo no usado de Plan Básico", "amount": -6000 },
{ "description": "Tiempo restante de Plan Premium", "amount": 18000 }
]
},
"subscription": {
"id": "9da5903d-3d1a-4f60-b487-b6b6cd7d9d1b",
"planId": "9a4698e5-d936-4298-84dc-4a770bfacc19",
"planName": "Plan Premium",
"status": "activa"
}
}

{danger} La suscripción está inactiva o cancelada code: 400

{
"changed": false,
"message": "La suscripción está inactiva; usa la renovación con pago para reactivarla con el nuevo plan."
}

Cambio de plan por invitación (opcional)

Si envías mode: "invitation", en lugar de aplicar el cambio se crea una invitación change_plan que se envía por correo al suscriptor. El cambio se ejecuta solo cuando el suscriptor la acepta. Rutas públicas del flujo:

  • GET /subscription-invitation/{token}: ver detalle de la invitación.
  • POST /subscription-invitation/{token}/accept: aceptar.
  • POST /subscription-invitation/{token}/decline: rechazar.

Ciclo de vida de la invitación
Vigencia 7 días desde el envío
Simultáneas Una sola invitación change_plan pendiente por suscripción. Una segunda llamada responde 400
Requisito El suscriptor debe tener una tarjeta guardada; si no, 400 sin enviar el correo
Al aceptar Se aplica el cambio y llega el webhook plan_changed, con transaction si hubo cobro
Al rechazar La invitación queda en declined. No se emite webhook
Al expirar La invitación deja de ser válida. Hoy no se emite ningún webhook al expirar

{warning} Como no hay evento de expiración, si dependes de la invitación no dejes el cambio en «pendiente» para siempre: guarda la fecha de envío y date por vencido a los 7 días. Puedes confirmar el estado real con un GET a la suscripción y comparar el plan.

En ambos modos, si la suscripción tiene webhook_url, se notifica el evento plan_changed. El cuerpo incluye previous_plan_id con el plan que tenía antes.

Previsualizar cambio de plan

Descripción: Previsualiza el prorrateo de un cambio de plan sin aplicarlo (la factura que se generaría con el cambio). Ideal para mostrarle al cliente cuánto se le cobrará o acreditará antes de confirmar.

Nombre del campo Descripción Reglas
plan_id Id del plan destino, como parámetro de consulta. Debe ser de tu comercio y del mismo ambiente que la suscripción. Aquí no se exige que esté activo ['required', 'exists:subscription_plans,id'] 

curl -X GET\
"/api/v1/subscriptions/subscription/9da5903d-3d1a-4f60-b487-b6b6cd7d9d1b/change-plan-preview?plan_id=9a4698e5-d936-4298-84dc-4a770bfacc19"\
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H "Content-type: application/json"

{success} Respuesta satisfactoria code: 200

{
"proration": {
"currency": "COP",
"unused_fraction": 0.6,
"credit_unused": 6000,
"charge_new": 18000,
"net": 12000,
"line_items": [
{ "description": "Tiempo no usado de Plan Básico", "amount": -6000 },
{ "description": "Tiempo restante de Plan Premium", "amount": 18000 }
]
}
}

Aplicar cupón

Descripción: Aplica un cupón (por su código) a una suscripción. El descuento se refleja en los cobros recurrentes según la duración del cupón (once, repeating o forever).

Nombre del campo Descripción Reglas
code Código del cupón a aplicar. Debe existir en tu comercio, estar activo y todavía ser redimible ['required', 'string'] 

curl -X POST\
"/api/v1/subscriptions/subscription/9da5903d-3d1a-4f60-b487-b6b6cd7d9d1b/apply-coupon"\
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H "Content-type: application/json" \
-d '{ "code": "WELCOME10" }'

{success} Respuesta satisfactoria code: 200

{
"applied": true,
"coupon_id": "9b0f2a13-2c44-4a1a-9f2e-1d3b4c5d6e7f",
"discount_ends_at": "2026-12-30 00:00:00"
}

{danger} Cupón inválido o no disponible code: 400

{
"applied": false,
"message": "Cupón inválido o no disponible."
}

Listar facturas

Descripción: Lista las facturas de una suscripción. Cada factura representa un ciclo de facturación con su estado (open, paid, void, uncollectible), subtotal, impuesto, total y período.

{success} Respuesta satisfactoria code: 200

{
"current_page": 1,
"data": [
{
"id": "9b0f4d21-8a3e-4c9b-9a1e-2f3a4b5c6d7e",
"number": "INV-2026-000012",
"status": "paid",
"subtotal": 12605.04,
"discount_total": 0,
"tax_total": 2394.96,
"total": 15000,
"currency_type": "COP",
"period_start": "2026-07-01 00:00:00",
"period_end": "2026-08-01 00:00:00",
"paid_at": "2026-07-01 19:00:05",
"subscription_id": "9da5903d-3d1a-4f60-b487-b6b6cd7d9d1b"
}
],
"total": 1,
"last_page": 1
}

Próxima factura (vista previa)

Descripción: Vista previa (borrador) de la próxima factura de la suscripción, con el descuento vigente ya aplicado. No genera ningún cobro.

{success} Respuesta satisfactoria code: 200

{
"upcoming_invoice": {
"status": "draft",
"currency_type": "COP",
"subtotal": 12605.04,
"tax_total": 2394.96,
"total": 15000,
"period_start": "2026-08-01 00:00:00",
"next_charge_at": "2026-08-01",
"line_items": [
{ "description": "Suscripción Plan Básico", "amount": 15000, "quantity": 1 }
]
}
}

Descargar factura en PDF

Descripción: Descarga el PDF de una factura específica de la suscripción. La respuesta es el archivo PDF (application/pdf).

curl -X GET\
"/api/v1/subscriptions/subscription/9da5903d-3d1a-4f60-b487-b6b6cd7d9d1b/invoices/your-invoice-id/pdf"\
-H 'Authorization: Bearer ACCESS_TOKEN' \
--output factura.pdf

Historial de transacciones

Descripción: Devuelve el historial paginado de cobros (transacciones) realizados por la suscripción, con el detalle de cada pago y su estado.

{success} Respuesta satisfactoria code: 200

{
"data": [
{
"id": "01990bf8-e20c-72e4-b408-991e81f70beb",
"amount": 15000,
"currency_type": "COP",
"tax": 0,
"next_renew_at": "2025-09-02",
"charge_at": "2025-09-02 14:48:06",
"approved": 1,
"subscription_id": "01990bf8-e1f3-7067-9c51-7bb4d1ad05bf",
"transaction": {
"transaction_id": 548,
"amount": 15000,
"currency_iso": "COP",
"amount_cop": 15000,
"tax": 0,
"reference_1": "Subscription: 01990bf8-e1f3-7067-9c51-7bb4d1ad05bf",
"reference_2": "Email: sdfasd@fsdfsd.ds",
"reference_3": "1756842484281",
"status": "Aprobada",
"payment_method": "credit",
"payment_method_source": "Visa",
"network": "credibanco",
"trazability_id": "548",
"authorization_code": "548",
"approved_at": "2025-09-02 14:48:04",
"expired_at": "2025-09-03 14:48:04",
"office_id": 1,
"environment": "production",
"aggregator": true,
"economic_group_id": 1,
"created_at": "2025-09-02 14:48:04",
"customer_payer_id": "01976094-220e-719d-aa2a-7bca1b757f59",
"customer_payer": {
"email": "sdfasd@fsdfsd.ds",
"name": "Osmi Otalora",
"identification_type": "CC",
"id_number": "101006464",
"dialling_code": "57",
"cellphone": "3006776454",
"country": "COL",
"state": "Bogota",
"city": "Bogota",
"address_1": "Bogota",
"address_2": "Bogota",
"zip_code": "0000"
},
"subscription_id": "01990bf8-e1f3-7067-9c51-7bb4d1ad05bf"
}
}
],
"links": {
"first": "http://localhost:8009/api/v1/subscriptions/subscription/01990bf8-e1f3-7067-9c51-7bb4d1ad05bf/transaction-history?page=1",
"last": "http://localhost:8009/api/v1/subscriptions/subscription/01990bf8-e1f3-7067-9c51-7bb4d1ad05bf/transaction-history?page=1",
"prev": null,
"next": null
},
"meta": {
"current_page": 1,
"from": 1,
"last_page": 1,
"links": [
{
"url": null,
"label": "&laquo; Anterior",
"active": false
},
{
"url": "http://localhost:8009/api/v1/subscriptions/subscription/01990bf8-e1f3-7067-9c51-7bb4d1ad05bf/transaction-history?page=1",
"label": "1",
"active": true
},
{
"url": null,
"label": "Siguiente &raquo;",
"active": false
}
],
"path": "http://localhost:8009/api/v1/subscriptions/subscription/01990bf8-e1f3-7067-9c51-7bb4d1ad05bf/transaction-history",
"per_page": 15,
"to": 1,
"total": 1
}
}

Próxima transacción (próximo cobro)

Descripción: Devuelve la información del próximo cobro recurrente pendiente: cuánto y cuándo se cobrará. Si aún no hay un cobro programado, transaction será null.

{success} Respuesta satisfactoria code: 200

{
"id": "01990bf8-eadc-7064-9996-06f08a7fbcd5",
"amount": 15000,
"currency_type": "COP",
"tax": 0,
"next_renew_at": "2025-10-02",
"charge_at": null,
"approved": null,
"subscription_id": "01990bf8-e1f3-7067-9c51-7bb4d1ad05bf",
"transaction": null
}