Una suscripción te permite cobrar a un cliente de forma periódica.

Los clientes pueden iniciar una suscripción lo que activará una autorización de pago al comienzo de cada ciclo de facturación.

El objeto subscription

Atributos


id string

Identificador único del objeto.


object string

Indica el tipo de objeto. Valor siempre será subscription.


amount integer

Un número entero positivo que representa cuánto cobrar en la unidad monetaria más pequeña (por ejemplo, 100 centavos para cobrar USD $ 1,00 o 100 para cobrar CLP $ 100)


billing_cycle_anchor enum

Representa cuando se debe dar inicio al primer ciclo de facturación.

Se puede dar inicio inmediatamente apenas se autorice la suscripción o en un día del mes específico para suscripciones de renovación mensual.

Posibles valores
now
Un día del mes entre 1 y 31

cancel_at datetime

Fecha de cancelación de la suscripción. Puede ser una fecha futura.


cancel_url string

Una URL a la cual el cliente será redirigido si la autorización del pago falla.


cancel_url_method enum

El método HTTP a utilizar al redirigir al cliente en caso de un pago fallido.

Posibles valores
post default
get

canceled_at datetime

Fecha a la que se canceló efectivamente la suscripción.


collection_method enum

Indica la suscripción se cobra de manera automática en un método de pago inscrito o manual con el envío de una nota de venta.

Posibles valores
automatic
send_invoice

currency string

Código de moneda ISO de tres letras. Corresponde a la moneda de presentación.


customer object expandible

Objeto customer relacionado.


customer_id string

ID customer relacionado.


custom_fields array of strings

Listado de datos personalizados que el cliente deberá llenar antes de poder autorizar el pago.

Posibles valores: given-name, family-name, address, tel, taxid, bday.


current_period_starts_at datetime

Fecha de inicio del periodo de suscripción vigente.


current_period_ends_at datetime

Fecha de término del periodo de suscripción vigente.


cycles integer

Cantidad de ciclos de facturación generados.
Si la suscripción se inicia con un 1er ciclo de facturación parcial con un proration_behavior igual a none, ese 1er ciclo no se incluirá en este conteo.


default_payment_method object expandible

Objeto payment_method relacionado.

Método de pago donde realizar los cargos en las renovaciones automáticas.


default_payment_method_id string

ID payment_method relacionado.


default_products array of objects

Listado de productos (product) activos e inactivos relacionados a la suscripción.


default_tax_rates array of objects

Listado de impuestos (tax_rate) activos e inactivos relacionados a la suscripción.


description string

Un texto arbitrario asociado al objeto.


duration integer

Duración máxima de la suscripción en número de ciclos de facturación.


interval enum

Determina el ciclo de facturación. Para las suscripciones automáticas, se creará un nuevo pago y se intentará una autorización al comienzo de cada ciclo.

Posibles valores
1day
1week
2weeks
1month
3months
6months
1year

live boolean

Indica si el pago existe en modo live o modo test.


metadata object

Conjunto de pares llave-valor que puedes asociar a un objeto.
Esto puede resultar útil para almacenar información adicional sobre el objeto en un formato estructurado.


name string

El nombre de la suscripción. Se le mostrará al cliente.


plan object expandible

Objeto plan relacionado.
Presente si la suscripción se creó a partir de un plan.


plan_id string

ID plan relacionado.


products array of objects

Listado de productos (product) activos relacionados a la suscripción.


proration_behavior enum

Determina como manejar los prorrateos resultantes de billing_cycle_anchor. Si el primer ciclo de facturación es parcial, puedes decidir si se realiza un cobro por el total del plan, proporcional o sin costo.

Posibles valores
create_prorations
full
none

return_url string

Una URL la cual el cliente podrá visualizar y seguir cada vez que ingrese a la pantalla de la suscripción.


return_url_method enum

El método HTTP a utilizar al redirigir al cliente en caso de ingresar a la URL anterior.

Posibles valores
post default
get

status enum

El estado de la suscripción.

Posibles valores
incomplete

Estado inicial de la suscripción.
La suscripción ha sido creada pero aún no ha sido iniciada por el cliente o está a la espera de una acción por tu parte.
trialing

Iniciada exitosamente por el cliente y se encuentra dentro de un periodo de facturación libre de cobro.
Una vez finalizado el periodo de trial se intentará realizar el primer cobro al cliente.
active

La suscripción tiene un cobro exitoso para el periodo de facturación vigente.
past_due

No se logró realizar un cobro exitoso al momento de renovar la suscripción y se está dentro del periodo de reintento automático de cobro.
Si se supera el periodo de reintento automático de cobro sin lograr un cobro exitoso, entonces la suscripción cambiará de estado a unpaid o canceled según la configuración de tu cuenta. En ambos casos la suscripción dejerá de renovarse automáticamente.
unpaid

No se logró realizar un cobro exitoso dentro del periodo de reintento automático de cobro.
No debieras permitir el acceso a tus productos o servicios si la suscripción se encuentra en este estado.
canceled

No se renovará en los siguientes ciclos de facturación.
Es posible llegar a este estado si la suscripción fue cancelada por el cliente o por ti, como también al no lograr un cobro exitoso dentro del periodo de reintento automático de cobro, según la configuración de tu cuenta.
No debieras permitir el acceso a tus productos o servicios si la suscripción se encuentra en este estado.
suspended

Se renovará automáticamente pero no se realizarán cobros al momento de renovar.
Se utiliza cuando necesitas pausar los cobros automáticos sin cancelar la suscripción.

status_reason string

Incluye detalles sobre una suscripción fallida o cancelada.


subtotal integer

Un número entero positivo que representa cuánto cobrar sin incluir impuestos excluyentes ni descuentos.


success_url string

Una URL a la cual el cliente será redirigido si la autorización del pago es exitosa.


success_url_method enum

El método HTTP a utilizar al redirigir al cliente en caso de un pago exitoso.

Posibles valores
post default
get

suspended_at datetime

Fecha de suspensión de la suscripción.


tax_rates array of objects

Listado de impuestos (tax_rate) activos relacionados a la suscripción.


trial_days integer

Duración del periodo de trial en días.


trial_starts_at datetime

Fecha de inicio del periodo de trial.


trial_ends_at datetime

Fecha de término del periodo de trial.


url string

Una URL utilizada para identificar de forma exclusiva el objeto. Las URL se pueden usar para compartir un pago en aplicaciones de mensajería, códigos QR y otros canales.


created_at datetime

Fecha de creación del objeto en formato ISO 8601. Basado en UTC.


updated_at datetime

Fecha de actualización del objeto en formato ISO 8601. Basado en UTC.