Saltar al contenido principal
POST
Crear la suscripción junto con su primer pagoEste endpoint inicia una suscripción a partir de un vaulted_token que ya tienes. Si el cliente se registra y paga al mismo tiempo, puedes enviar un bloque subscription en Crear pago: una sola llamada cobra la tarjeta y crea la suscripción a partir de ese mismo cobro. Esa ruta está documentada solo para pagos con tarjeta sin fricción. Consulta Inicia una suscripción con el primer pago.
Aplicar una promoción al crear la suscripciónEnvía promotion con un id o un code para aplicar una promoción asociada al plan. El primer cobro lleva el descuento. La suscripción debe estar en un plan que tenga la promoción asociada. La suscripción almacena su propia copia de la promoción, que no se edita después. Consulta Promociones en planes de suscripción.
Una promoción AUTOMATIC asociada al plan se aplica por sí sola cuando la suscripción se crea en ese plan. Si la solicitud también envía una promotion, gana el descuento mayor; los dos no se acumulan.
Finalización de la suscripciónLos campos billing_cycles y availability.finish_at se afectan entre sí. Si ambos se completan al crear la suscripción, esta pasará al estado COMPLETED al llegar al evento más cercano definido en esos campos, ya sea el ciclo de facturación o el finish_at correspondiente.
Uso de credenciales para un CIT previoSi creas un pago CIT (por ejemplo, Apple Pay o tarjeta) antes de crear la suscripción y pasas el vaulted token resultante a la suscripción, debes incluir payment_method.card.usage para indicar si es el primer uso o uno posterior. Sin esto, los cobros recurrentes se tratarán como CIT y el proveedor los rechazará.El payload requerido para suscripciones nuevas es:

Errores de promoción

Crear una suscripción con promotion puede fallar con los códigos de abajo. En cada caso, no se crea nada. Una promoción AUTOMATIC asociada al plan se maneja de forma distinta. Si no se puede aplicar, porque está deshabilitada, venció o no tiene usos restantes, la suscripción se crea sin ella y la solicitud igualmente tiene éxito. Lo mismo ocurre cuando el servicio de promociones no encuentra la promoción asociada. Solo un 503 o 504 detiene la creación. Consulta la sección Códigos de respuesta HTTP para ver los detalles de los posibles resultados de error.

Configurar una regla de reembolso

refund_rule se puede definir al crear la suscripción para configurar cómo se calcula un reembolso CUSTOM cuando una solicitud de cancelación posterior no incluye su propio refund_amount:
PERCENT y FIXED son excluyentes: una regla PERCENT solo lleva percent (0–100) y una regla FIXED solo lleva amount. El amount.currency de una regla FIXED debe ser igual a la moneda de la propia suscripción. Se puede cambiar o eliminar más adelante en Actualizar suscripción y se describe en el objeto Subscription. Consulta Cancelar suscripción para ver cómo se usa. Está disponible para las organizaciones habilitadas; contacta a Yuno. Para las demás, enviar refund_rule se ignora en silencio y no se almacena nada.

Autorizaciones

public-api-key
string
header
predeterminado:<Your public-api-key>
requerido
private-secret-key
string
header
predeterminado:<Your private-secret-key>
requerido

Encabezados

x-idempotency-key
string
predeterminado:{$randomUUID}

Un identificador único para la solicitud. Debe ser diferente cada vez (UUID). Consulta autenticación.

Cuerpo

application/json
name
string
requerido

El nombre del plan de suscripción (MAX 255; MIN 3).

account_id
string
requerido

El identificador único de la cuenta que tendrá disponible el plan de suscripción para usar (UUID, 36 caracteres).

country
string
requerido

El país de la suscripción (MAX 2; MIN 2; ISO 3166-1).

customer_payer
object
requerido

Especifica el objeto customer_payer para identificar al cliente. Obligatorio. Ten en cuenta que los errores de validación de este objeto nombran el campo customer_payer.code, no customer_payer.id; por ejemplo 400 BAD_REQUEST ("customer_payer.code field is required") cuando se omite.

payment_method
object
requerido

Especifica el objeto payment_method. Los tipos admitidos son CARD, PAYPAL_ENROLLMENT y PIX_AUTOMATIC, todos con métodos de pago inscritos previamente (vaulted_token)

description
string

La descripción del plan de suscripción (MAX 255; MIN 3).

merchant_reference
string

Identificación del plan de suscripción (MAX 255; MIN 3).

soft_descriptor
string

Descriptor de estado de cuenta que se muestra en el extracto bancario del titular de la tarjeta. Cuando se define, se guarda en la suscripción y se propaga a cada pago de refacturación generado por el motor de suscripciones. Los límites de longitud y formato varían según el proveedor (por ejemplo, Unlimit lo trunca a 22 caracteres y Airwallex a 30). Worldpay no lee este campo; construye la narrativa del extracto a partir de payment_description.

Maximum string length: 255
amount
object

Especifica el objeto amount, con el valor de cada pago de la suscripción y la moneda utilizada. Es mutuamente excluyente con plan_id: envía exactamente uno de los dos.

plan_id
string

El identificador único de un plan al que suscribir a este cliente. Es mutuamente excluyente con amount: envía exactamente uno de los dos. Omite trial_period y billing_date cuando se define: ambos se heredan del plan y la solicitud se rechaza con 400 BAD_REQUEST si los envías. Omite también frequency: también se hereda del plan, pero enviarla no se rechaza: se ignora en silencio y la frecuencia del plan la reemplaza. Si el plan tiene su propia configuración de reintentos, omite también retries: la suscripción hereda los reintentos del plan, y enviar ambos se rechaza con 400 INVALID_PARAMETERS.

additional_data
object

Indica el objeto additional_data. Este objeto no es obligatorio. Sin embargo, si envías esta información, la experiencia de pago de tu usuario mejora.

frequency
object

Especifica el objeto frequency. Define la frecuencia de facturación de la suscripción. Incluye type y value.

billing_cycles
object

Especifica el objeto billing_cycles. Define el número de cobros asociados a la suscripción. Si se omite, la suscripción no tiene límite de ciclos y sigue facturando hasta que se cancela o llega a availability.finish_at, si hay uno definido.

trial_period
object

Especifica el objeto del período de prueba

availability
object

Indica el objeto availability. Define el intervalo de fechas, con fecha de inicio y de fin, en el que la suscripción está disponible.

metadata
object[]

Conjunto de pares clave-valor que puedes adjuntar a un objeto. Puede ser útil para guardar información adicional sobre el objeto en un formato estructurado. Las claves se pueden eliminar enviando un valor vacío en metadata. Puedes agregar hasta 50 objetos de metadata.

retries
object

Especifica el objeto 'retries'. Indica si se deben reintentar las transacciones rechazadas en Yuno y el monto si es necesario. Con plan_id, envía retries solo cuando el plan no tiene una configuración de reintentos propia. Si el plan define reintentos, la suscripción los hereda y una solicitud que también envíe retries se rechaza con 400 INVALID_PARAMETERS.

initial_payment_validation
boolean

Indicador para identificar si la suscripción debe esperar el primer pago para continuar. Es False por defecto.

billing_date
object

Especifica el objeto billing_date. Define el tipo de fecha que se usa para la lógica de la suscripción. Es mutuamente excluyente con el objeto frequency.

subscription_agreement_id
string

Vincula esta suscripción con el pago inicial creado con el mismo ID de acuerdo. Se usa para el seguimiento, la conciliación y la gestión de contracargos. Debe coincidir exactamente con el subscription_agreement_id enviado en payment_method.detail.card.stored_credentials.subscription_agreement_id en el pago de origen (MAX 255).

refund_rule
object

Configura la regla de reembolso que se usa para resolver un reembolso de cancelación CUSTOM posterior cuando esa solicitud de cancelación no envía su propio refund_amount. Disponible para las organizaciones habilitadas; contacta a Yuno.

promotion
object

Aplica una promoción asociada al plan en el que se crea esta suscripción. Envía exactamente uno entre id o code. La promoción comienza con la suscripción y descuenta el primer cobro. Si no se puede aplicar (no está asociada al plan, venció, está deshabilitada, aún no comienza o no tiene usos disponibles), la solicitud se rechaza y no se crea nada. Si el plan también tiene una promoción automática, se aplica el mayor descuento en el primer cobro, y la promoción que envías gana en caso de empate. Consulta Promociones en planes de suscripción.

Respuesta

201

id
string
Ejemplo:

"0c7fed3e-ee0d-4d34-9547-778be4ec0798"

name
string
Ejemplo:

"Test Subscription"

account_id
string
Ejemplo:

"493e9374-510a-4201-9e09-de669d75f256"

country
string
Ejemplo:

"US"

description
string | null
Ejemplo:

"Subscription Test"

merchant_reference
string
Ejemplo:

"subscription-ref-merchant-AA01"

soft_descriptor
string | null
Ejemplo:

"ACME SUBSCRIPTION"

status
string
Ejemplo:

"ACTIVE"

amount
object
frequency
object
billing_cycles
object
customer_payer
object
payment_method
object
availability
object
trial_period
object
metadata
any
plan_id
string

Solo está presente cuando la suscripción está vinculada a un plan.

plan_assigned_at
string

Solo está presente en suscripciones vinculadas a un plan. El momento en que se asoció el plan: en la creación a partir de un plan, en la migración a un plan o en un cambio de plan.

previous_subscription_id
string

Solo está presente cuando esta suscripción se creó por un cambio de plan (cambiar una suscripción existente a un plan diferente).

current_phase
string

Solo está presente en suscripciones vinculadas a un plan.

billing_phases
object[]

Solo está presente en suscripciones vinculadas a un plan cuyo plan tiene fases. Contiene únicamente las fases TRIAL iniciales, capturadas en la creación; la fase terminal REGULAR nunca se incluye, ya que su precio no se fija y se resuelve a partir del plan en cada facturación.

subscription_agreement_id
string | null
Ejemplo:

"sa_6af2dfcd-44c0-4f16-a331-8bed3ed9c9fa"

created_at
string
Ejemplo:

"2024-09-30T12:04:23.265372Z"

updated_at
string
Ejemplo:

"2024-09-30T12:04:23.265372Z"

current_period_start
string | null

Inicio del período de facturación en el que está la suscripción actualmente, una cadencia antes de current_period_end. Dentro de una prueba o de cualquier otra fase del plan, sigue la cadencia de esa fase. Una suscripción terminal (CANCELED o COMPLETED) conserva su ventana final en lugar de pasar a null. Es null solo para una suscripción sin cadencia recurrente. Siempre se devuelve junto con current_period_end.

Ejemplo:

"2023-01-16T20:00:00.912480Z"

current_period_end
string | null

Fin del período de facturación en el que está la suscripción actualmente. Es igual a billing_cycles.next_at. Siempre se devuelve junto con current_period_start.

Ejemplo:

"2023-02-16T20:00:00.786342Z"

billing_date
object | null

Solo está presente en suscripciones facturadas en una fecha fija en lugar de una frecuencia; es mutuamente excluyente con frequency.

retries
object | null

La política de reintentos que se aplica cuando se rechaza un cobro recurrente. Consulta Reintentos.

additional_data
object | null

El enriquecimiento opcional de la orden enviada en la creación, devuelto tal cual. Consulta El objeto Suscripción para ver su estructura completa.

initial_payment_validation
boolean

Indica si la suscripción esperó a que su primer pago fuera exitoso antes de activarse. Es false por defecto.

Ejemplo:

false

reason
string | null

Motivo libre del estado actual de la suscripción, cuando se registró uno; null en caso contrario.

Ejemplo:

"merchant request"

renewal_notification_days
integer | null

Cuántos días antes de la próxima fecha de facturación se envía el webhook subscription.close_to_renewal. null significa que no se envía ninguna notificación de renovación.

Ejemplo:

3

payments
string[]
cancellation_time
string | null

Cuándo se canceló la suscripción. Solo se define una vez que llega a CANCELED; null en caso contrario.

Ejemplo:

"2023-12-16T20:46:54.786342Z"

cancellation_source
string | null

Qué desencadenó la cancelación: MERCHANT, SYSTEM, PLAN_CHANGE o RETRIES_EXHAUSTED. Solo se define una vez que la suscripción llega a CANCELED; null en caso contrario. Trátalo como un valor abierto: maneja los valores no reconocidos de forma adecuada.

Ejemplo:

"MERCHANT"

ending_time
string | null

Cuándo se completó o expiró la suscripción. Solo se define una vez que llega a COMPLETED; null en caso contrario.

Ejemplo:

"2024-12-16T20:46:54.786342Z"

phases
object[]

Las definiciones de fases del plan vinculado, tal como las declara el plan, incluida la fase terminal REGULAR. Solo está presente en suscripciones vinculadas a un plan que tiene fases. Esta es la escalera propia del plan, no la instantánea de este suscriptor: para lo que se fijó para esta suscripción en la creación, usa billing_phases.

current_phase_end
string | null

Cuándo la fase indicada por current_phase pasa a la siguiente: para una suscripción en su prueba, cuándo cambia al precio regular. Es el fin del último período de facturación que cubre la fase, así que en el último período de una prueba es igual a current_period_end. Es null para una suscripción sin plan y para una que ya salió de la escalera de fases.

Ejemplo:

"2023-03-16T20:00:00.786342Z"

pending_plan_change
object | null

El cambio de plan programado para el próximo ciclo de facturación, o null cuando no hay ninguno pendiente. Programa uno con el bloque plan_change en Update Subscription.

refund_rule
object

La regla de reembolso almacenada que se usa para resolver un reembolso de cancelación CUSTOM cuando la solicitud de cancelación no envía su propio refund_amount. Solo está presente cuando hay una configurada; se omite, no es null, en caso contrario. Disponible para las organizaciones habilitadas; contacta a Yuno.

pause_until
string

Cuándo está programado que la suscripción se reanude automáticamente. Solo está presente en una suscripción actualmente pausada con una duración (pause_cycles o pause_until enviados al pausar); está ausente, no es null, en cualquier otra lectura.

Ejemplo:

"2026-10-15T15:54:22.780166Z"

cancel_scheduled
object | null

null cuando no hay ninguna cancelación pendiente.

refund
object | null

null cuando refund fue NONE o se omitió. Está presente en la respuesta de cancelación y en cada lectura posterior una vez calculado.

unpaid_cycle
object

Solo está presente cuando el ciclo de facturación actual está en PAST_DUE y no se ha liquidado.