Sign in
subscriptions

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.

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 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.

put/subscriptions/{id}

Path parameters

idstring required

ID de la suscripción

Headers

X-SECRET-KEYstring required

Tu clave secreta de API.

Una llave de cuenta (sk_live_..., sk_test_...) opera sobre su propia cuenta y, con X-ACCOUNT-ID, sobre sus cuentas conectadas.

Una llave de organización (sk_org_live_..., sk_org_test_...) alcanza todas las cuentas de una organización y solo sirve para leer: saldos, movimientos y reportes. Para operar sobre una cuenta debe nombrarla con X-ACCOUNT-ID; omitirlo en una lectura devuelve todas las cuentas de la organización. Cualquier otro endpoint responde 403 con code: organization_key_unsupported.

Request body

OR
OR

Response

Suscripción actualizada

idstring

ID único de la suscripción

descriptionstring

Descripción de la suscripción

status'active' | 'paused' | 'past_due' | 'cancelled'

Estado de la suscripción

created_atstring date-time

Fecha de creación

updated_atstring date-time

Última actualización

current_period_startstring date-time nullable

Inicio del período de facturación actual

current_period_endstring date-time nullable

Fin del período de facturación actual

tax_namestring nullable

Nombre fiscal del suscriptor

tax_idstring nullable

ID fiscal del suscriptor

resumes_onstring date nullable

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

next_payment_attempt_atstring date-time nullable

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.

test_clock_idstring nullable

ID del test clock heredado del Customer. Solo está presente en un Sandbox nombrado.

Changes