Suscripción

Las suscripciones te permiten cobrar a un cliente de forma recurrente.

Objeto de suscripción

Suscripción

string

read-onlyrequired

Identificador único del objeto.

Example:

sub_IiFWdYgq7QIrx1nkvDcOhXqi

customer

string

required

Identificación del cliente asociado a la suscripción.

Example:

cus_TgfdA2vL9rnWblZM8LtWMsdY

items

array[object (Items) {9}]

required

Lista de items de la suscripción, cada uno con un precio adjunto.

string

read-onlyrequired

Identificador único del objeto.

Example:

si_d7d2UrHwSG5A5YkYF7vfZmFf

name

string

read-onlyrequired

Nombre del producto del producto, al momento de asociarlo a la suscripción.

Example:

Nombre del producto

unit_price

string

optional

Precio unitario a cobrar del item. Al asociar un precio a un object, si no se define, se utiliza el precio unitario configurado en el precio.

Example:

20000.00

quantity

integer

required

Cantidad a cobrar del item.

>= 1

Example:

subtotal

string

read-onlyoptional

Subtotal a cobrar del item antes, antes de descuentos.

Example:

20000.00

total

string

read-onlyoptional

Total a cobrar del item, despues de descuentos.

Example:

20000.00

product

object (Producto)

read-onlyoptional

Producto asociado al item.

price

object (Precio)

read-onlyoptional

Precio asociado al item.

price

string

write-onlyrequired

El ID del objeto de precio.

Example:

price_1Q8VwAGkNzLGa86BS12312

discounts

array[object (Descuentos) {6}] | null

optional

Lista de descuentos de la suscripción, cada uno con un cupon adjunto.

string

read-onlyrequired

Identificador único del objeto.

Example:

sd_aYbDFQaOd7TmBl0I58D5ax8l

code

string

required

Código del cupon de descuento. Debe estar previamente creado en Treli.

Example:

10OFF

amount

string

read-onlyrequired

Valor en dinero del descuento, representado como una cadena flotante con dos decimales.

Example:

10000.00

percent

string | null

read-onlyoptional

Valor en porcentaje del descuento, representado como una cadena flotante con dos decimales. Únicamente aplica si el cupón type=percent

Example:

10.00

duration_in_collections

integer | null

optional

Duración del descuento en número de cobros. Únicamente aplica si el cupón duration=repeating. Si no se define el valor, se utilizará la duración definida en el cupón.

>= 1

elapsed_duration

integer

read-onlyoptional

Si el cupón duration=repeating, define el número de cobros en el cual el descuento ha sido aplicado. Cuando elapsed_duration=duration_in_collections, el cupón es eliminado automáticamente de la suscripción.

taxes

array [object {4}] | null

read-onlyoptional

Lista de impuestos de la suscripción. Este objeto es solo lectura y se define según las retenciones enviadas en invoice_retentions. Unicamente disponible si haces uso de la automatización contable en Treli para la generación automática de facturas.

type

string

required

name

string

required

tax_id

string

required

total

string

required

latest_collection

string

read-onlyrequired

El cobro más reciente que esta suscripción ha generado.

Example:

col_75jaKNHdYNfFpooDaDJKIMtu

subtotal

string

read-onlyrequired

Subtotal de la suscripción, antes de descuentos e impuestos, representado como una cadena flotante con dos decimales.

Example:

20000.00

total

string

read-onlyrequired

Total de la suscripción despues de descuentos e impuestos, representado como una cadena flotante con dos decimales.

Example:

20000.00

currency

enum<string>

required

Código de moneda ISO de tres letras, en mayúsculas.

>= 3 characters<= 3 characters

Allowed values:

COPUSDBRLMXNPENARSCLP

Example:

COP

collection_method

enum<string>

required

Al cobrar automáticamente, Treli intentará cobrar esta suscripción utilizando el método de pago predeterminado asociada al cliente o utilizando el valor enviado en payment_method. Al enviar notificaciones de cobro al cliente para que la pague manualmente, Treli enviará una notificaciones de cobro a tu cliente cliente con las instrucciones de pago y marcará la suscripción como active.

Allowed values:

chargecollect

Example:

charge

status

enum<string>

read-onlyrequired

Para collection_method=charge, una suscripción pasa a estado incompleto si falla el primer intento de cobro. Una vez pagado el primer cobro, la suscripción pasa a estado active. Si el primer cobro no se paga en 23 horas, la suscripción pasa a estado expired. Este es un estado terminal; el cobro pendiente se anulará y no se generarán más cobros.

Una suscripción que actualmente se encuentra en un período de prueba está en trialing y, si el cobro despúes de que finaliza el período de prueba es exitoso, pasa a estar active. de lo contrario, pasa a estar past_due.

Una suscripción con collection_method=charge pasa a past_due cuando se requiere un pago, pero no se puede realizar (debido a un pago fallido o a la espera de acciones adicionales del usuario). Una vez que Treli haya agotado todos los reintentos de pago, la suscripción se pasará a canceledo unpaid (según tu configuración de reintentos y recordatorios).

Una suscripción con collection_method=collect pasará a past_duecuando la el cobro no se paga antes de la fecha de vencimiento, y canceled o unpaid si sigue sin pagarse en una fecha límite posterior (según tu configuración de reintentos y recordatorios). Ten en cuenta que cuando una suscripción tiene el estado de unpaid, no se intentará generar cobros posteriores.

Allowed values:

activecanceledpending_cancelendedpast_dueunpaidtrialingpausedincompleteexpired

Example:

active

created_date

string <date-time>

read-onlyrequired

Fecha en la cual se creó el objeto.

Example:

2024-11-15 16:44:50

start_date

string <date-time> | null

read-onlyoptional

Fecha en la cual se inició la suscripción. Es definida cuando la suscripción cambia de estado, por primera vez, a active

Example:

2024-11-15 16:44:50

next_renewal_date

string <date-time> | null

read-onlyoptional

Fecha de la próxima renovación (cobro) de la suscripción.

Example:

2024-11-15 16:44:50

latest_renewal_date

string <date-time> | null

read-onlyoptional

Fecha de la última renovación (cobro) de la suscripción.

Example:

2024-11-15 16:44:50

canceled_at_date

string <date-time> | null

read-onlyoptional

Una fecha en el futuro en la que la suscripción se cancelará automáticamente, si la suscripción es cancelada al final del periodo actual.
Una fecha en el pasado, si la suscripción es cancelada inmediatamente o si una suscripción programada para ser cancelada ya se canceló.

resumes_at

string <date-time> | null

read-onlyoptional

Una fecha en el futuro en la que la suscripción se reactivara automáticamente, si la suscripción fue pausada con la opción de ser reactivada en una fecha futura.

ended_at_date

string <date-time> | null

read-onlyoptional

Una fecha en el pasado en la cual la suscripción finalizó. Aplica únicamente si una suscripción es creada con duration>1

expires_at_date

string <date-time> | null

read-onlyoptional

Una fecha en el futuro en la que la suscripción expirará. Aplica únicamente si una suscripción es creada con collection_method=charge y el primer cobro no es pagado en un período de 23 horas.

paused_at_date

string <date-time> | null

read-onlyoptional

Una fecha en el futuro en la que la suscripción fue pausada.

billing_period

string

read-onlyrequired

Define la frecuencia de facturación. Es decir, la frecuencía en la cual la suscripción generará cobros autom automáticamente.

Example:

month

billing_interval

string

read-onlyrequired

Define la el intervalo del periodo

>= 1 characters

Example:

trial_days

number | null

optional

Entero que representa el número de días del período de prueba antes de que se le cobre al cliente por primera vez.

payment_method

string | null

optional

ID del método de pago predeterminado de la suscripción. Debe pertenecer al cliente asociado a la suscripción. Si no se define ninguno, la suscripción y el cobro utilizarán el método de pago predeterminado del cliente, en caso de que exista. Sólo permitido si collection_method=charge.
El valor puede ser null si el método de pago utilizado para cobrar la suscripción es el método de pago predeterminado del cliente.

payment_method_gateway

string | null

read-onlyoptional

Pasarela de pago asociada a el método de pago utilizado en la suscripción.

Example:

wompi

payment_method_type

string | null

read-onlyoptional

Tipo de método de pago utilizado en la suscripción.

Example:

card

is_test

boolean

read-onlyoptional

Tiene el valor false si el objeto existe en modo en producción o el valor true si el objeto existe en modo de prueba

Example:

false

days_until_due

integer | null

optional

Número de días que un cliente tiene para pagar los cobros generados por esta suscripción. Este valor será null para las suscripciones donde collection_method=charge. Sólo permitido si collection_method=collect.

>= 1

tag

string | null

optional

Etiqueta asociada a la suscripción.

exclude_from_batch

boolean

required

Tiene el valor false si la suscripción debe estar excluida de las operaciones masivas realizadas por medio del dashboard.

source

string

read-onlyrequired

Fuente por la cual se genero la suscripción

meta_data

object | null

optional

Conjunto de pares clave-valor que se pueden asociar a un objeto. Esto puede ser útil para almacenar información adicional sobre el objeto en un formato estructurado. Las claves se pueden eliminar publicando un valor vacío en los metadatos.

Example:

{"user_id":"261993"}

duration

integer | null

optional

Duración en número de cobros de la suscripción. Por ejemplo, si la duración se define como 4, la suscripción generará 4 cobros y despúes pasará a estado ended

>= 1

commitment_periods

integer | null

optional

Periodo de permanencia de la suscripción en número de cobros. Por ejemplo, si el periodo de permanencia se define como 4, el cliente no podra cancelar la suscripción si no hasta despúes de 4 cobros.

>= 1

cancelation_details

object | null

optional

Detalles sobre por qué se canceló la suscripción

feedback

enum<string> | enum<null>

optional

El motivo sobre por qué el usuario canceló la suscripción.

Allowed values:

customer_servicelow_qualitymissing_featuresswitched_servicetoo_complextoo_expensiveunusedother

comment

string | null

optional

Comentarios adicionales sobre por qué el usuario canceló la suscripción.

first_payment_invoicing

enum<string> | enum<null>

optional

Define el comportamiendo de la generación de factura para el primer cobro. create genera una factura de inmediato, antes de recibir el pago del primer cobro. after genera una factura desúes del recibir el pago del primer cobro.
Únicamente disponible si haces uso de la automatización contable en Treli para la generación automática de facturas.

Allowed values:

createafter

invoice_settings

object

required

Objeto con ajustes de facturación especificos para la suscripción, distintos a los definidos en la configuración general de facturación. Unicamente disponible si haces uso de la automatización contable en Treli para la generación automática de facturas.

invoice_document_id

string

required

invoice_cost_center

string

required

invoice_retentions

object

required

reteica

string

required

retefte

string

required

requires_shipping_address

boolean

required

payment_settings

null

required

Objeto de suscripción#

Objeto de suscripción