Skip to main content
Las suscripciones de duración indefinida son ideales cuando necesitas cobrar un monto fijo de manera recurrente (por ejemplo, mensual o anual) sin una fecha de término establecida. En Quentli existen dos tipos de suscripciones: las suscripciones con duración indefinida y las suscripciones con pagos definidos (duración definida). En esta guía veremos un ejemplo de integración donde se crea una suscripción con items recurrentes desde el inicio. Este caso de uso es útil cuando los importes de las solicitudes de pago son fijos y conocidos al momento de crear la suscripción.
Una suscripción de duración indefinida generará automáticamente las solicitudes de pago según la periodicidad configurada en los conceptos de pago.

​
Crea un cliente

El primer paso es crear un cliente, quien será el beneficiario de la suscripción.
POST /v1/customers
{
    "input": {
        "name": "Roberto Martínez",
        "username": "54321",
        "email": "roberto@ejemplo.com",
        "phoneNumber": "+525512345678"
    }
}

​
Crea un concepto de pago recurrente

Antes de crear la suscripción, necesitas definir un concepto de pago con detalles de recurrencia. Este concepto determinará el monto y la frecuencia de los cobros.

​
Ejemplo de solicitud

POST /v1/payment-concepts
{
  "input": {
    "displayName": "Membresía Premium",
    "amount": 49900,
    "currency": "MXN",
    "recurrentDetail": {
      "collectionInterval": "MONTH",
      "chargeEach": 1
    }
  }
}
El campo recurrentDetail define la frecuencia de cobro. En este ejemplo, interval: "MONTH" con chargeEach: 1 significa que se cobrará cada mes. También puedes usar "WEEK", "YEAR", o ajustar chargeEach para cobrar cada N periodos.

​
Crea una suscripción con items

Ahora que tenemos un cliente y un concepto de pago, podemos crear la suscripción proporcionando los items desde el inicio.

​
Ejemplo de solicitud

POST /v1/subscriptions
{
  "input": {
    "description": "Membresía Premium - Anual",
    "nextCollectionDate": "2025-02-01T06:00:00.000Z",
    "customerId": "cus_1234567890",
    "collectionMethod": "AUTOMATIC",
    "onlyAutomaticCollection": true,
    "items": [
      {
        "conceptId": "pc_9876543210",
        "quantity": 1
      }
    ]
  }
}
Observa cómo en este ejemplo proporcionamos el campo items con el conceptId del concepto de pago previamente creado. Esto hará que Quentli genere automáticamente las solicitudes de pago según la configuración de recurrencia del concepto.

​
Campos importantes

  • nextCollectionDate: La fecha en que se generará y cobrará la siguiente solicitud de pago.
  • collectionMethod: El método de cobranza para las solicitudes de pago generadas. AUTOMATIC intentará cobrar automáticamente.
  • onlyAutomaticCollection: Si es true, solo se permitirá usar métodos de pago que soportan cargos automáticos.
  • items: Un arreglo de items que contienen el conceptId del concepto de pago y la quantity.

​
Consulta las solicitudes de pago generadas

Una vez creada la suscripción, Quentli generará automáticamente las solicitudes de pago según la configuración. Puedes consultarlas filtrando por el ID de la suscripción.

​
Ejemplo de solicitud

GET /v1/invoices?filter[subscriptionId][equals]=sub_1234567890

​
Respuesta esperada

{
  "invoices": [
    {
      "id": "inv_1111111111",
      "customerId": "cus_1234567890",
      "subscriptionId": "sub_1234567890",
      "dueDate": "2025-02-01T06:00:00.000Z",
      "status": "SCHEDULED",
      "amount": 49900,
      "currency": "MXN",
      "items": [
        {
          "conceptId": "pc_9876543210",
          "displayName": "Membresía Premium",
          "quantity": 1,
          "amount": 49900
        }
      ]
    }
  ]
}

​
¿Qué sigue?

Dependiendo del método de cobranza y de la fecha de programación de las solicitudes de pago, Quentli realizará las siguientes acciones:
  • Generación automática: Quentli generará automáticamente la siguiente solicitud de pago según la periodicidad configurada (mensual, anual, etc.) después de que se complete cada cobro.
  • Cobro automático: Si el método de cobranza es AUTOMATIC, Quentli intentará cobrar el monto cuando se cumpla la fecha de programación.
  • Notificaciones: Si has configurado recordatorios, se enviarán automáticamente a los clientes antes de cada cobro.

​
Escucha el evento INVOICE_CREATED

Para mantenerte informado sobre las nuevas solicitudes de pago que se generan automáticamente, te recomendamos configurar un webhook para escuchar el evento INVOICE_CREATED. Este evento se dispara cada vez que se crea una nueva solicitud de pago, ya sea desde el Dashboard, la API, o automáticamente por una suscripción. 
{
  "eventId": "<id_de_evento>",
  "eventType": "INVOICE_CREATED",
  "data": {
    "invoiceId": "<id_de_solicitud_de_pago>",
    "amount": 49900,
    "customer": {
      "id": "cus_1234567890",
      "name": "Roberto Martínez",
      "email": "roberto@ejemplo.com",
      "phoneNumber": "+525512345678",
      "username": "54321"
    }
  }
}
Conoce más sobre webhooks y otros eventos disponibles
Para cancelar una suscripción de duración indefinida y detener la generación de nuevas solicitudes de pago, puedes usar el endpoint DELETE /v1/subscriptions/:id.
⌘I