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
subscriptionAtributos
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 ampliable
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 ampliable
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 ampliable
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 |
|---|
incompleteEstado 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. |
trialingIniciada 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. |
activeLa suscripción tiene un cobro exitoso para el periodo de facturación vigente. |
past_dueNo 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. |
unpaidNo 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. |
canceledNo 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. |
suspendedSe 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.