Referencia APISubscriptions

Actualizar una suscripción

Actualiza una suscripción. Puedes: - **Cambiar el método de pago**: Envía `payment_method_id` con el ID de un método de pago activo del suscriptor. Si la suscripción tiene un pago pendiente, se intentará cobrar automáticamente con el nuevo método de pago. - **Pausar**: Envía `act: "pause"`. Opcionalmente, incluye `resumes_on` para reactivación automática. - **Reactivar**: Envía `act: "unpause"`. - **Agregar o eliminar productos**: Envía un arreglo `items` con los cambios. Cada item identifica un precio con `price_id` o un producto con `product_id` (usa el primer precio del producto), y opcionalmente `quantity` (default `1`) o `deleted: true` para removerlo. Usa `mode` para decidir cuándo aplican: `"next_cycle"` (al siguiente cobro, default), `"now"` (inmediato; el prorrateo se suma al próximo cobro) o `"now_and_charge"` (inmediato y cobra el prorrateo al instante). Para previsualizar el prorrateo antes de aplicar, usa [`POST /subscriptions/{id}/proration_preview`](#tag/Subscriptions/operation/previewSubscriptionProration). Para un **cobro único o crédito** (una multa, un cargo puntual o un crédito de cortesía) tienes dos opciones: envía `add_invoice_items` en este mismo endpoint (se agregan como pendientes al próximo cobro, ideal para combinarlos con un cambio de productos en una sola llamada), o usa [`POST /one_time_payments`](#tag/One-Time-Payments/operation/createOneTimePayment) con `subscription_id` (que además permite cobrar de inmediato con `mode: now`). Un monto negativo es un crédito. Consulta o cancela los pendientes con `GET` y `DELETE /subscriptions/{subscription_id}/invoice_items`.

Authentication

X-SECRET-KEYstring
Tu clave secreta de API

Path parameters

idstringRequired

ID de la suscripción

Request

This endpoint expects an object.
Cambiar método de pagoobjectRequired
OR
Pausar o reactivarobjectRequired
OR
Modificar productos o agregar cobros únicosobjectRequired

Response

Suscripción actualizada

idstring

ID único de la suscripción

descriptionstring

Descripción de la suscripción

statusenum

Estado de la suscripción

created_atdatetime

Fecha de creación

updated_atdatetime

Última actualización

current_period_startdatetime or null

Inicio del período de facturación actual

current_period_enddatetime or null

Fin del período de facturación actual

tax_namestring or null
Nombre fiscal del suscriptor
tax_idstring or null
ID fiscal del suscriptor
resumes_ondate or null

Fecha de reactivación automática (si está pausada)

next_payment_attempt_atdatetime or null

Próximo intento de cobro automático (solo cuando el estado es past_due)

payment_retriesinteger

Número de reintentos de cobro realizados para el período actual. Recurrente intenta cobrar una vez al día por 15 días antes de cancelar la suscripción.

default_payment_methodobject or null

Método de pago predeterminado de la suscripción

subscriberobject
checkoutobject or null
productobject
transfer_setupslist of objects

Transferencias automáticas recurrentes de esta suscripción. En cada cobro exitoso, cada una transfiere su amount_percent del total de la factura a la cuenta destinataria.

proration_chargeobject or null

Presente solo con mode: now_and_charge: detalla el cobro inmediato del prorrateo. null en los demás modos.

Errors

400
Bad Request Error
404
Not Found Error
422
Unprocessable Entity Error