Actualizar una suscripción | Documentación API de Recurrente

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.

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

Pausar o reactivarobjectRequired

Modificar productos o agregar cobros únicosobjectRequired

Response

Suscripción actualizada

idstringOptional

ID único de la suscripción

descriptionstringOptional

Descripción de la suscripción

statusenumOptional

Estado de la suscripción

created_atdatetimeOptional

Fecha de creación

updated_atdatetimeOptional

Última actualización

current_period_startdatetime or nullOptional

Inicio del período de facturación actual

current_period_enddatetime or nullOptional

Fin del período de facturación actual

tax_namestring or nullOptional

Nombre fiscal del suscriptor

tax_idstring or nullOptional

ID fiscal del suscriptor

resumes_ondate or nullOptional

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

next_payment_attempt_atdatetime or nullOptional

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

payment_retriesintegerOptional

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.

metadatastring or double or booleanOptional

Metadata persistida durante todo el ciclo de vida de la suscripción y expuesta en sus webhooks.

test_clock_idstring or nullOptional

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

default_payment_methodobject or nullOptional

Método de pago predeterminado de la suscripción

subscriberobjectOptional

checkoutobject or nullOptional

productobjectOptional

transfer_setupslist of objectsOptional

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 nullOptional

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

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.

$	curl -X PUT https://app.recurrente.com/api/subscriptions/id \
>	-H "X-SECRET-KEY: <apiKey>" \
>	-H "Content-Type: application/json" \
>	-d '{
>	"payment_method_id": "pay_m_7v5ie3pw"
>	}'

1	{
2	"id": "su_nehndm7j",
3	"description": "One Free-Testable Banana",
4	"status": "active",
5	"default_payment_method": {
6	"id": "pay_m_7v5ie3pw",
7	"type": "card",
8	"card": {
9	"last4": "4242",
10	"network": "visa"
11	}
12	}
13	}