Listar los cobros de una suscripción
Tu clave API privada (comienza con pvk_)
In: header
Tu ID de organización
In: header
Path Parameters
uuidQuery Parameters
Límite en el número de objetos a devolver. El límite puede estar entre 1 y 100, y el valor predeterminado es 10
1 <= value <= 100Un cursor para paginación. starting_after es el ID de la última solicitud de la página anterior: la respuesta empieza en la siguiente
uuidUn cursor para paginación. ending_before es el ID de la primera solicitud de la página siguiente: la respuesta termina en la anterior
uuidResponse Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://api.venflow.app/v1/subscriptions/497f6eca-6276-4993-bfeb-53cbbbba6f08/charges"{
"data": [
{
"amount": 0.1,
"charge_date": "string",
"created": 0.1,
"currency": "USD",
"failure_reason": "string",
"id": "string",
"invoice": "string",
"livemode": true,
"metadata": {
"property1": "string",
"property2": "string"
},
"object": "charge",
"payment": "string",
"retry_policy": "none",
"status": "scheduled",
"subscription": "string"
}
],
"has_more": true,
"object": "list",
"url": "string"
}{
"code": "not_found",
"details": {},
"message": "string"
}{
"code": "not_found",
"details": {},
"message": "string"
}{
"code": "not_found",
"details": {},
"message": "string"
}{
"code": "not_found",
"details": {},
"message": "string"
}{
"code": "not_found",
"details": {},
"message": "string"
}{
"code": "not_found",
"details": {},
"message": "string"
}Cancelar una suscripción POST
Cancela una suscripción al final del período en curso, igual que el panel de Venflow. - La suscripción pasa a `cancelling` y el campo `cancel_at_period_end` de la respuesta queda en `true`: el cliente conserva el acceso hasta que cierre el período, y ahí se cancela sola. No se genera un cobro nuevo. - `cancel_mode` es opcional y hoy solo acepta `period_end`, que es también el valor por defecto. La cancelación inmediata todavía no está disponible: si envías otro valor, responde 400. - Cancelar una suscripción ya cancelada no falla: la respuesta devuelve el estado actual. - Para revertir una cancelación programada usa `POST /v1/subscriptions/{id}/undo-cancel`; para revivir una ya cancelada, `POST /v1/subscriptions/{id}/reactivate`. - **No dispara el webhook `SUBSCRIPTION_CANCELLED_EVENT` al llamarlo.** Ese evento se emite cuando el sistema cancela la suscripción, lo que incluye la llegada del fin del período de una cancelación programada. Si tu integración necesita reaccionar en el momento de la llamada, hazlo en tu propio código. Programa la cancelación al final del período en curso, igual que el panel de Venflow: la suscripción se cancela sola al cerrar el ciclo y el cliente conserva el acceso hasta entonces. Se revierte con el endpoint de deshacer cancelación.
Crear un cobro POST
Crea una solicitud de cobro sobre una suscripción de cobro por API (`collection_mode` externo): tú decides cuándo y cuánto se cobra, y Venflow ejecuta el débito contra la domiciliación que el cliente ya autorizó. Requiere el header `Idempotency-Key`. Repetir la llamada con la misma clave devuelve la solicitud original, sin generar un segundo débito. Sin `amount` se cobra el precio actual del plan; sin `charge_date` el cobro se ejecuta en la próxima corrida del motor (hoy). La respuesta confirma únicamente que la solicitud quedó creada o programada: los bancos son asíncronos, así que el resultado (pagado o rechazado) llega después por webhook. `currency` define en qué moneda va `amount`. Con `USD` (predeterminado) es un monto neto en dólares, igual que el precio del plan: el IVA se calcula encima y los bolívares se obtienen a la tasa BCV del día del cobro. Con `VES` es el débito exacto en bolívares de ese día, con el equivalente en dólares de la factura derivado a esa misma tasa; en ese caso `amount` es obligatorio, porque el plan no tiene precio en bolívares. `retry_policy` define qué pasa si el banco rechaza el débito. Con `none` (predeterminado) es un solo intento: la solicitud queda `failed` y reintentar es tu decisión (una solicitud nueva). Con `automatic` la factura entra a la cola de reintentos de Venflow con los reintentos y los días que tu organización tiene configurados, y la solicitud se resuelve una sola vez al final.