Saltar al contenido principal
PATCH
Update Subscription
Transición de la suscripciónLos campos billing_cycles y availability.finish_at se influyen 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. Son condiciones de finalización independientes: la primera que se cumpla completa la suscripción.Cuando se incluye el objeto availability, finish_at se aplica tal como se envía: si lo omites o lo envías como null, se elimina cualquier fecha de finalización definida antes, por lo que la suscripción queda sin fecha de fin y sigue renovándose hasta que se cancele. Esto significa que, cuando actualices availability.start_at, debes incluir finish_at en la misma solicitud si quieres conservar la fecha de finalización. start_at no se comporta así: si lo omites, la fecha de inicio actual no cambia. Si omites el objeto availability completo, ambas fechas permanecen sin cambios.Ten en cuenta que availability.start_at solo puede moverse a una fecha anterior al actualizar. Enviar una fecha posterior devuelve un error 400: The availability start date cannot be greater than the current availability start date.
Actualización retroactiva de credencialesSi tienes suscripciones existentes cuyos cobros recurrentes fallan por falta de uso de credenciales (por ejemplo, a partir de un pago CIT inicial), puedes usar este endpoint PATCH para definir payment_method.card.usage de forma retroactiva y corregir el problema.
Cambios de plan programadosUsa el bloque plan_change para mover una suscripción a otro plan con efecto en su siguiente ciclo de facturación, sin prorrateo y sin cobro a mitad de ciclo. La suscripción debe estar ACTIVE o TRIALING y ya tener un plan; el plan de destino debe estar activo y solo puede haber un cambio pendiente a la vez. Envía "plan_change": null para deshacer un cambio pendiente; omitir el campo nunca lo modifica. El cambio pendiente se devuelve como pending_plan_change en este endpoint y en el objeto de suscripción, y los webhooks subscription.plan_change_scheduled, subscription.plan_change_canceled y subscription.plan_changed registran su ciclo de vida.El plan administra amount, frequency, billing_date y country, y no se pueden enviar para una suscripción vinculada a un plan: combinar cualquiera de ellos con plan_change devuelve 400.
Cambios de plan inmediatosEnvía "effective": "IMMEDIATE" dentro de plan_change para aplicar el cambio en esta llamada en lugar de programarlo: la suscripción conserva su id, el precio del nuevo plan se factura desde el siguiente cobro y, a diferencia de un cambio programado, esto funciona incluso en el último ciclo de facturación. Un cambio inmediato mientras hay otro cambio pendiente devuelve 409 PLAN_CHANGE_ALREADY_SCHEDULED; primero deshaz el pendiente con "plan_change": null.billing_cycle_behavior decide qué ocurre con el ancla de facturación cuando el plan cambia en el mismo lugar:
  • KEEP (predeterminado, omitir el campo se comporta igual): la fecha del siguiente cobro no se modifica; solo cambia el precio.
  • RESTART: el siguiente cobro se vuelve a anclar al momento del cambio más la frecuencia del nuevo plan. Solo se restablece el ancla: los contadores de ciclos de facturación, la configuración de reintentos y el estado de la suscripción se conservan. RESTART requiere effective: IMMEDIATE y devuelve 400 con un cambio programado; KEEP junto con un cambio programado se acepta y simplemente programa el cambio como de costumbre: un cambio programado nunca mueve el ancla de todos modos.
Un cambio inmediato emite el webhook subscription.plan_changed en el momento de la llamada: subscription.plan_change_scheduled nunca se dispara para él y pending_plan_change permanece en null en todo momento.billing_cycle_behavior es solo de escritura: se acepta en la solicitud y nunca se devuelve en ninguna respuesta.En una suscripción mensual creada sin un frequency.monthly_billing_day explícito, RESTART establece ese campo con el día del reinicio, y cada renovación futura lo lee: reiniciar el día 15 factura el día 15 de ahí en adelante, no solo en el siguiente ciclo. Una suscripción que ya declara un día de facturación lo conserva: la fecha no se mueve al día del reinicio, solo se vuelve a anclar la hora del día. El valor se devuelve en el objeto de suscripción, por lo que se puede leer después del cambio. La misma regla se aplica a RESTART en Reanudar suscripción: es una sola regla, en ambos endpoints.
Reiniciar el ciclo de facturación sin un planPara una suscripción que no está vinculada a un plan, billing_cycle_behavior está disponible como campo de nivel superior en este endpoint, normalmente combinado con un cambio de frequency en la misma llamada, por ejemplo, pasar a un suscriptor de mensual a anual y reiniciar el ciclo desde hoy. Se aplica la misma semántica de KEEP/RESTART y, en una suscripción que aún no ha comenzado, la fecha vuelta a anclar se ajusta a su availability.start_at.Reglas de ubicación: en una suscripción vinculada a un plan, el campo de nivel superior devuelve 400 (el ancla se administra mediante plan_change), y combinar el campo de nivel superior con un bloque plan_change devuelve 400: usa plan_change.billing_cycle_behavior en su lugar. Una suscripción PAUSED devuelve 409 INVALID_SUBSCRIPTION_STATUS: se acepta un reinicio mientras la suscripción está ACTIVE, TRIALING o PAST_DUE, o mientras aún está CREATED, donde (a diferencia de plan_change) la solicitud se permite y la fecha vuelta a anclar se ajusta a availability.start_at. Un reinicio de nivel superior no emite ningún webhook: lee el nuevo ancla desde el objeto de suscripción.
Promociones de la suscripciónEnvía promotion con un id o un code para aplicar una promoción asociada al plan de la suscripción. La suscripción debe estar ACTIVE o TRIALING. El descuento entra en vigor desde el siguiente cobro. La respuesta incluye el objeto promotion. Aplicar una promoción mientras hay otra activa la reemplaza: la actual termina con end_reason REPLACED y la nueva empieza con 0 ciclos usados.
Para eliminar la promoción activa, usa Remove Promotion from Subscription.Una solicitud que envía promotion no debe enviar nada más. Combinada con plan_change, responde 400 INVALID_PARAMETERS con el mensaje A promotion and a plan change cannot be sent in the same update, so send them in two requests. Combinada con cualquier otro campo, como name o metadata, responde 400 BAD_REQUEST con el mensaje a promotion must be sent alone; send the other changes in a separate request. No se cambia nada en ninguno de los dos casos. Envía los campos en solicitudes separadas.
Promociones en un cambio de planDos campos opcionales en plan_change deciden qué ocurre con una promoción activa:
  • promotion_behavior: KEEP (predeterminado) conserva la promoción, con sus ciclos restantes, en el nuevo plan. END la termina con end_reason PLAN_CHANGE. Se ignora cuando no hay ninguna promoción activa.
  • apply_new_plan_promotion: true (predeterminado) aplica la promoción AUTOMATIC del nuevo plan, si tiene una, y termina la promoción actual con PLAN_CHANGE. false deja sin aplicar la promoción del nuevo plan, y promotion_behavior decide qué ocurre con la actual.
Consulta Cambios de plan para ver el resultado en cada momento.

Errores de cambio de plan

Cada uno de los errores 409 y 422 de abajo incluye un campo current_status junto con code y messages, con el estado de la suscripción en el momento en que se rechazó la solicitud. La solicitud rechazada no realiza ningún cambio.
409 Conflict
Una suscripción CANCELED o COMPLETED se rechaza antes con 400 INVALID_STATE, que no incluye current_status. Los problemas de validación en el propio bloque (un plan_id faltante, un effective no admitido, un plan de destino en otra moneda o una escalera HONOR_PHASES más larga que los ciclos de facturación restantes) devuelven 400 BAD_REQUEST sin current_status. Lo mismo aplica a los errores de ubicación de billing_cycle_behavior: RESTART sin effective: IMMEDIATE, el campo de nivel superior combinado con plan_change, o el campo de nivel superior en una suscripción vinculada a un plan devuelven cada uno 400 BAD_REQUEST con un mensaje que indica la corrección. Dónde se detecta un valor no válido de billing_cycle_behavior depende de su posición: el campo de nivel superior se rechaza en el borde de la API como 400 INVALID_PARAMETERS ("The field 'billing_cycle_behavior' has an invalid value."), mientras que un valor incorrecto anidado dentro de plan_change llega al motor y devuelve 400 BAD_REQUEST (p. ej., "RESET is invalid for plan_change.billing_cycle_behavior field"): trata ambos códigos como fallas de validación. Una excepción a la tabla de errores de cambio de plan anterior: PLAN_CHANGE_NOT_AVAILABLE se aplica solo a los cambios programados. Un cambio IMMEDIATE no necesita un ciclo próximo, por lo que se acepta en el último ciclo de facturación.

Definir una regla de reembolso

refund_rule configura cómo se calcula un reembolso CUSTOM cuando una solicitud de cancelación posterior no incluye su propio refund_amount. Se define aquí o al crear, y enviar "refund_rule": null la elimina.
PERCENT y FIXED son excluyentes: se rechaza una regla que incluya tanto percent como amount, y también una que no incluya ninguno para su propio type. El amount.currency de una regla FIXED debe ser igual a la moneda de la propia suscripción; enviar una que no coincida devuelve 400 REFUND_RULE_CURRENCY_MISMATCH: "refund_rule.amount.currency USD must match the subscription currency COP." (las monedas varían según la solicitud). La misma verificación se aplica cuando la actualización cambia el amount.currency de la propia suscripción mientras aún hay almacenada una regla FIXED en la moneda anterior, sin modificar refund_rule en la misma solicitud: 400 REFUND_RULE_CURRENCY_MISMATCH: "stored refund rule is FIXED in COP; send refund_rule in USD or refund_rule: null in the same request." (con los nombres de las monedas involucradas). Vuelve a enviar la regla en la nueva moneda, o elimínala, en la misma solicitud que cambia amount.currency. Después de eliminarla, refund_rule se omite del objeto de suscripción en la respuesta: nunca se devuelve como null. Consulta Cancelar suscripción para ver cómo se usa la regla, y El objeto de suscripción para la referencia de campos. Disponible para las organizaciones habilitadas; contacta a Yuno: en una organización que no está habilitada, enviar refund_rule (incluido null) se ignora en silencio y no cambia nada.

Autorizaciones

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

Parámetros de ruta

subscription_id
string
requerido

El identificador único de la suscripción.

Cuerpo

application/json
name
string

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

description
string

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

account_id
string

El identificador único de la cuenta que tendrá disponible el plan de suscripción para usar (MAX 64 ; MIN 36).

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. Actualizarlo cambia el descriptor que se aplica a las refacturaciones posteriores generadas 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
country
string

El país de la suscripción.

amount
object

Especifica el objeto amount, con el valor de cada pago de la suscripción y la moneda utilizada.

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.

customer_payer
object

Especifica el objeto customer_payer para identificar al cliente.

payment_method
object

Especifica el objeto payment_method. Los tipos admitidos son CARD y PAYPAL_ENROLLMENT. Cuando envías payment_method, type y vaulted_token son obligatorios, incluso si solo cambias card.usage.

availability
object

Especifica el objeto availability. Define un intervalo de fechas, basado en las fechas de inicio y fin, en el que la suscripción está disponible para usar. Si este objeto se omite de la solicitud, las fechas de disponibilidad se dejan sin cambios. Cuando se incluye, omitir finish_at (o enviarlo como null) elimina cualquier fecha de fin definida previamente; omitir start_at deja sin cambios la fecha de inicio actual.

retries
object

La configuración de reintentos que se aplicará de ahora en adelante. Acepta el mismo objeto que Create Subscription, incluidos strategy y schedule, excepto cancel_on_exhausted_retries, que solo se puede definir al crear. Los cambios se aplican la próxima vez que se programen reintentos: un ciclo de facturación que ya está ejecutando sus reintentos termina con la configuración con la que empezó, y la actualización entra en vigor desde el siguiente ciclo.

plan_change
object | null

Mueve la suscripción a otro plan. effective: NEXT_BILLING_CYCLE (el valor por defecto) programa el cambio para la próxima renovación: sin prorrateo y sin cobro a mitad de ciclo. effective: IMMEDIATE aplica el cambio en el mismo lugar, en esta llamada: la suscripción conserva su id, el precio del nuevo plan se factura desde el próximo cobro y billing_cycle_behavior decide qué ocurre con el ancla de facturación. La suscripción debe estar ACTIVE o TRIALING y ya estar en un plan; el plan de destino debe estar ACTIVE. En los cambios programados solo puede haber uno pendiente a la vez: envía "plan_change": null para deshacerlo antes de que se aplique (un cambio IMMEDIATE mientras hay otro pendiente devuelve 409). amount, frequency, billing_date y country los gestiona el plan y no se pueden enviar para una suscripción vinculada a un plan: combinar cualquiera de ellos con plan_change devuelve 400.

billing_cycle_behavior
enum<string>

Para suscripciones que no están vinculadas a un plan: reubica la facturación de la misma manera que plan_change.billing_cycle_behavior, normalmente combinado con un cambio de frequency en la misma llamada (por ejemplo, de mensual a anual, reiniciando el ciclo desde hoy). KEEP (por defecto): la fecha del próximo cobro no se modifica. RESTART: reubica el próximo cobro en ahora más la frecuencia (posiblemente actualizada); solo se reinicia el ancla: los contadores de ciclos, la configuración de reintentos y el estado de la suscripción se conservan. En una suscripción que aún no ha comenzado (CREATED, que aquí se acepta, a diferencia de plan_change), el ancla se ajusta a su fecha de inicio. Reglas: no se puede combinar con plan_change (400: usa el campo anidado); en una suscripción vinculada a un plan este campo devuelve 400 (se gestiona mediante plan_change); una suscripción PAUSED devuelve 409 INVALID_SUBSCRIPTION_STATUS. Solo escritura: nunca se repite en ninguna respuesta.

Opciones disponibles:
KEEP,
RESTART
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 individuales se pueden eliminar enviándoles un valor vacío. Todas las claves se pueden eliminar enviando un valor vacío en metadata.

refund_rule
object | null

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. Envía null para borrar una regla configurada previamente.

promotion
object

Aplica una promoción asociada al plan de la suscripción. Envía exactamente uno entre id o code. La suscripción debe estar ACTIVE o TRIALING, y el descuento se aplica desde el siguiente cobro. Aplicar una promoción mientras otra está activa la reemplaza: la actual termina con end_reason REPLACED, y la nueva comienza con 0 ciclos usados. Consulta Promociones en planes de suscripción.

Respuesta

200

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

Descriptor suave.

Ejemplo:

"ACME SUBSCRIPTION"

status
string
Ejemplo:

"ACTIVE"

amount
object
frequency
object
billing_cycles
object
customer_payer
object
payment_method
object
availability
object
metadata
any
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.

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.

trial_period
object

Período de prueba.

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[]
subscription_agreement_id
string | null

ID del acuerdo de suscripción.

Ejemplo:

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

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"

plan_id
string

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

Ejemplo:

"00000000-0000-4000-8000-000000000001"

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.

Ejemplo:

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

previous_subscription_id
string | null

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

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
string

Solo está presente en suscripciones vinculadas a un plan.

Ejemplo:

"REGULAR"

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"

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. current_phase: "REGULAR" es la señal de que la escalera se agotó.

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.

promotion
object

La copia de la promoción almacenada en la suscripción. Consulta El objeto Subscription Promotion.