Actualizar suscripción
Actualiza los campos de una suscripción, incluida la adición retroactiva de datos de uso de credenciales almacenadas.
PATCH para definir payment_method.card.usage de forma retroactiva y corregir el problema.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."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.RESTARTrequiereeffective: IMMEDIATEy devuelve400con un cambio programado;KEEPjunto con un cambio programado se acepta y simplemente programa el cambio como de costumbre: un cambio programado nunca mueve el ancla de todos modos.
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.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.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.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.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.ENDla termina conend_reasonPLAN_CHANGE. Se ignora cuando no hay ninguna promoción activa.apply_new_plan_promotion:true(predeterminado) aplica la promociónAUTOMATICdel nuevo plan, si tiene una, y termina la promoción actual conPLAN_CHANGE.falsedeja sin aplicar la promoción del nuevo plan, ypromotion_behaviordecide qué ocurre con la actual.
Errores de cambio de plan
Cada uno de los errores409 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.
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
Cuerpo
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.
255Especifica 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.
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.
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.
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.
KEEP, RESTART 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.
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.
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
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.
"2023-01-16T20:00:00.912480Z"
La política de reintentos que se aplica cuando se rechaza un cobro recurrente. Consulta Reintentos.
El enriquecimiento opcional de la orden enviada en la creación, devuelto tal cual. Consulta El objeto Suscripción para ver su estructura completa.
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.
"MERCHANT"
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.
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.
"2023-03-16T20:00:00.786342Z"
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ó.
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.
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.
"2026-10-15T15:54:22.780166Z"
La copia de la promoción almacenada en la suscripción. Consulta El objeto Subscription Promotion.