---
title: "Actualizar una suscripción"
method: PUT
path: "/subscriptions/{id}"
tags: ["subscriptions"]
---

# Actualizar una suscripción

`PUT /subscriptions/{id}`

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

## Path parameters

- `id` string, required

## Headers

- `X-SECRET-KEY` string, required

## Request body

- union
  - SubscriptionsUpdateSubscriptionRequest0
    - `payment_method_id` string, required — ID del método de pago activo del suscriptor (ej. `pay_m_7v5ie3pw`)
  - SubscriptionsUpdateSubscriptionRequest1
    - `act` 'pause' | 'unpause', required — Acción a realizar: `pause` para pausar, `unpause` para reactivar
    - `resumes_on` string, date — (Opcional, solo para `pause`) Fecha en la que la suscripción se reactivará automáticamente (formato YYYY-MM-DD)
  - SubscriptionsUpdateSubscriptionRequest2
    - `mode` 'next_cycle' | 'now' | 'now_and_charge' — Cuándo se aplican los cambios: - `next_cycle` (default): espera al siguiente cobro y no genera ajuste. - `now`: aplica inmediatamente y suma un prorrateo por los días que falten del ciclo actual al próximo invoice (cobro adicional al agregar, crédito al eliminar). - `now_and_charge`: aplica inmediatamente y cobra el prorrateo al instante al método de pago de la suscripción (equivalente a `always_invoice` de Stripe). Requiere un prorrateo neto positivo y mayor al mínimo de la moneda, y un método de pago; de lo contrario responde `422`. Si el cobro se rechaza, no se aplica ningún cambio. Para un cambio que resulte en crédito o en un monto menor al mínimo, usa `now`.
    - `items` SubscriptionsIdPutRequestBodyContentApplicationJsonSchemaOneOf2ItemsItems[] — Lista de cambios. Cada item es un producto a agregar (default) o a eliminar (`deleted: true`).
      - `price_id` string — ID del precio recurrente (ej. `pr_abc123`). Acepta también `product_id`; si pasas ambos, `price_id` gana.
      - `product_id` string — ID del producto. Si lo usas, se utiliza el primer precio del producto. Útil cuando aún no conoces el `price_id`.
      - `quantity` integer — (Opcional) Cantidad para agregar. Default `1`. Ignorado cuando `deleted: true`.
      - `deleted` boolean — (Opcional) Si es `true`, elimina ese precio de la suscripción en lugar de agregarlo.
    - `add_invoice_items` SubscriptionsIdPutRequestBodyContentApplicationJsonSchemaOneOf2AddInvoiceItemsItems[] — Cobros únicos (cargos o créditos) que se agregan como InvoiceItems pendientes al próximo cobro de la suscripción — equivalente a `add_invoice_items` de Stripe. Puedes enviarlos solos o junto con `items` (todo se aplica en una sola operación atómica). Un monto negativo es un crédito.
      - `amount_in_cents` integer, required — Monto en centavos, en la moneda de la suscripción. Negativo = crédito.
      - `description` string, required — Descripción del cobro (ej. "Multa por mora").

## Response `200`

Suscripción actualizada

- SubscriptionsUpdateSubscriptionResponse200
  - `id` string — ID único de la suscripción
  - `description` string — Descripción de la suscripción
  - `status` 'active' | 'paused' | 'past_due' | 'cancelled' — Estado de la suscripción
  - `created_at` string, date-time — Fecha de creación
  - `updated_at` string, date-time — Última actualización
  - `current_period_start` string, date-time, nullable — Inicio del período de facturación actual
  - `current_period_end` string, date-time, nullable — Fin del período de facturación actual
  - `tax_name` string, nullable — Nombre fiscal del suscriptor
  - `tax_id` string, nullable — ID fiscal del suscriptor
  - `resumes_on` string, date, nullable — Fecha de reactivación automática (si está pausada)
  - `next_payment_attempt_at` string, date-time, nullable — Próximo intento de cobro automático (solo cuando el estado es `past_due`)
  - `payment_retries` integer — 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.
  - `metadata` union
    - string
    - number, double
    - boolean
  - `test_clock_id` string, nullable — ID del test clock heredado del Customer. Solo está presente en un Sandbox nombrado.
  - `default_payment_method` SubscriptionsIdPutResponsesContentApplicationJsonSchemaDefaultPaymentMethod — Método de pago predeterminado de la suscripción
    - `id` string — ID del método de pago
    - `type` string — Tipo de método de pago
    - `card` SubscriptionsIdPutResponsesContentApplicationJsonSchemaDefaultPaymentMethodCard
      - `last4` string — Últimos 4 dígitos de la tarjeta
      - `network` string — Red de la tarjeta
  - `subscriber` Subscriber
    - `id` string — ID del usuario suscriptor
    - `first_name` string, nullable
    - `last_name` string, nullable
    - `full_name` string, nullable
    - `email` string, email
    - `phone_number` string, nullable
  - `checkout` SubscriptionsIdPutResponsesContentApplicationJsonSchemaCheckout
    - `id` string — ID del checkout que originó la suscripción
  - `product` SubscriptionsIdPutResponsesContentApplicationJsonSchemaProduct
    - `id` string — ID del producto asociado
  - `transfer_setups` TransferSetup[] — 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.
    - `id` string — ID de la configuración de transferencia
    - `status` 'pending' | 'completed' | 'cancelled' | 'reversed' — En pagos únicos: `pending` mientras el cobro no se completa y `completed` cuando la transferencia se ejecutó. En suscripciones la configuración queda `pending` mientras la suscripción está activa. `cancelled` si el checkout, la suscripción o un reembolso canceló el setup antes de ejecutarlo; `reversed` si un reembolso devolvió una transferencia ya completada.
    - `amount_in_cents` integer, nullable — Monto fijo en centavos a transferir (pagos únicos). No puede exceder el monto neto disponible después de fees, FEL e IVA.
    - `amount_percent` number, double, nullable — Porcentaje del total de cada factura a transferir (suscripciones).
    - `currency` string — Moneda
    - `recipient_id` string — ID de la cuenta de Recurrente que recibe los fondos (no es una cuenta bancaria).
    - `purpose` 'fund_split' | 'platform_commission' — Qué representa la transferencia. `fund_split` (el valor predeterminado) es una distribución ordinaria de fondos: enruta parte del cobro a otra cuenta, sin más consecuencias. `platform_commission` marca la transferencia como la comisión que una cuenta conectada paga a su plataforma — es lo que crean `application_fee_amount` / `application_fee_percent` — y cambia tres comportamientos: solo puede fluir de la cuenta conectada hacia su plataforma (sobre una conexión activa), es la única que un reembolso revierte con `refund_application_fee: true`, y se incluye en la facturación diaria de comisiones (DTE) cuando la conexión la tiene habilitada.
  - `application_fee_percent` number, double, nullable — Comisión de plataforma como porcentaje del total de cada factura. `null` cuando la suscripción no paga comisión.
  - `proration_charge` SubscriptionsIdPutResponsesContentApplicationJsonSchemaProrationCharge — Presente solo con `mode: now_and_charge`: detalla el cobro inmediato del prorrateo. `null` en los demás modos.
    - `amount_in_cents` integer
    - `currency` string
    - `status` string

## Other responses

- `400` — Acción inválida
- `404` — Método de pago no encontrado
- `422` — No se puede realizar la acción. Con `mode: now_and_charge` también ocurre cuando el cambio no genera un cobro inmediato (crédito o monto menor al mínimo — usa `now`), cuando la suscripción no tiene método de pago, o cuando el cobro del prorrateo es rechazado (en cuyo caso no se aplica ningún cambio).

## Changes

- **2026-09-02** `da12dce50f30` — 1 info
  - added the optional property `application_fee_percent` to the response with the `200` status

[Change history](https://skmtc.dev/recurrente/apis/referencia-api/changes/subscriptions/:id/put.md)

---

[API](https://skmtc.dev/recurrente/apis/referencia-api.md) · [All operations](https://skmtc.dev/recurrente/apis/referencia-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/recurrente/referencia-api/revisions/da12dce50f30/schema)