---
title: "Actualizar un producto"
method: PUT
path: "/products/{id}"
tags: ["products"]
---

# Actualizar un producto

`PUT /products/{id}`

Actualiza un producto existente. Para actualizar el precio, incluye el `id` del precio dentro de `prices_attributes`.

Si el precio tiene suscripciones (activas, pausadas o con pago pendiente), no se modifica en su lugar:
se archiva y se crea un precio de reemplazo con un `id` nuevo, que viene en la respuesta — guárdalo si
almacenas IDs de precios. Las suscripciones existentes conservan el precio archivado (mismo monto y plan).
Crear un checkout con el `id` de un precio archivado usa automáticamente su reemplazo vigente.
Enviar una actualización con el `id` de un precio archivado responde `400` indicando el precio vigente.

## Path parameters

- `id` string, required

## Headers

- `X-SECRET-KEY` string, required

## Request body

- object
  - `product` ProductsIdPutRequestBodyContentApplicationJsonSchemaProduct, required
    - `name` string — Nuevo nombre del producto
    - `description` string
    - `image_url` string
    - `success_url` string, uri
    - `cancel_url` string, uri
    - `payment_method_types` ProductsIdPutRequestBodyContentApplicationJsonSchemaProductPaymentMethodTypesItems[] — (Opcional) Métodos de pago habilitados para este producto: `card` (tarjeta, pago de contado), `bank_transfer` (transferencia bancaria), `stablecoins` (dólares digitales), `balance` (Balance Recurrente). Al enviarlo, el producto usa su propia configuración en vez de heredar la de la cuenta; los valores no reconocidos se ignoran. Omítelo para heredar la configuración de la cuenta. Las cuotas son un eje aparte (`available_installments`); `card` controla el pago de contado, no las cuotas.
    - `available_installments` ProductsIdPutRequestBodyContentApplicationJsonSchemaProductAvailableInstallmentsItems[] — (Opcional) Opciones de cuotas (en meses) disponibles para este producto, independientes de `payment_method_types`. Solo aplica a `GTQ` y requiere que la cuenta tenga pagos con tarjeta habilitados. En los checkouts de este producto, el comprador escoge entre estas opciones. Usa `[]` para ocultar cuotas, o una lista como `[3]` para mostrar solo esa opción.
    - `metadata` object
    - `custom_fields` CheckoutCustomFieldRequest[] — (Opcional) Lista completa de campos personalizados. Reemplaza los existentes. Para actualizar uno, incluye su `id`. Para archivarlo, marca `_destroy: true`.
      - `id` string — ID del campo existente (para actualizar). Omítelo para crear.
      - `_destroy` boolean — Si es `true`, archiva el campo. Solo aplica si incluyes `id`.
      - `key` string, required — Identificador estable, alfanumérico con guión bajo.
      - `type` 'text' | 'numeric' | 'dropdown', required
      - `label` string, required — Etiqueta visible para el cliente. Recurrente la traduce automáticamente.
      - `optional` boolean
      - `minimum_length` integer
      - `maximum_length` integer
      - `default_value` string
      - `options` CheckoutCustomFieldRequestOptionsItems[] — Requerido para `type: dropdown`. Hasta 200 opciones.
        - `label` string, required
        - `value` string, required
    - `prices_attributes` ProductsIdPutRequestBodyContentApplicationJsonSchemaProductPricesAttributesItems[] — Para actualizar el precio, incluye el `id` del precio existente
      - `id` string, required — ID del precio existente (requerido para actualizar)
      - `amount_in_cents` integer — Nuevo monto en centavos
      - `proration_behavior` 'none' | 'create_prorations' — (Opcional) Controla el primer cobro de nuevas suscripciones. Ver descripción completa en el endpoint de creación de productos.
      - `billing_cycle_anchor_day` integer — (Opcional) Día del mes (1–31) para cobros recurrentes de nuevas suscripciones. Si el mes tiene menos días, se cobra el último día.
      - `defer_to_billing_day` boolean — (Opcional) Si es `true`, las nuevas suscripciones difieren su primer cobro hasta la próxima ocurrencia de `billing_cycle_anchor_day`. Ver descripción completa en el endpoint de creación de productos.

## Response `200`

Producto actualizado

- Product
  - `id` string — ID único del producto
  - `status` string — Estado del producto
  - `name` string — Nombre del producto
  - `description` string, nullable — Descripción del producto
  - `success_url` string, nullable — URL de redirección después de un pago exitoso
  - `cancel_url` string, nullable — URL de redirección cuando el comprador cancela
  - `custom_terms_and_conditions` string, nullable — Términos y condiciones personalizados
  - `phone_requirement` 'none' | 'optional' | 'required' — Requerimiento de teléfono
  - `address_requirement` 'none' | 'optional' | 'required' — Requerimiento de dirección
  - `billing_info_requirement` 'none' | 'optional' | 'required' — Requerimiento de información fiscal
  - `has_dynamic_pricing` boolean — Si usa precio dinámico
  - `payment_method_types` ProductPaymentMethodTypesItems[] — Métodos de pago habilitados para este producto, ya resueltos (cuando el producto hereda la configuración de la cuenta, refleja los métodos de la cuenta): `card` (tarjeta, pago de contado), `bank_transfer` (transferencia bancaria), `stablecoins` (dólares digitales), `balance` (Balance Recurrente). Las cuotas se exponen por separado en `available_installments`.
  - `available_installments` integer[] — Opciones de cuotas (en meses) que se mostrarán en el checkout, independientes de `payment_method_types`. Vacío si no se ofrecen cuotas. Solo aplica a GTQ.
  - `prices` Price[] — Precios del producto
    - `id` string — ID único del precio
    - `status` 'active' | 'archived' — Estado del precio. Un precio `archived` fue reemplazado y ya no acepta nuevas compras; las suscripciones existentes lo conservan.
    - `amount_in_cents` integer — Monto en centavos
    - `currency` 'GTQ' | 'USD' — Moneda
    - `charge_type` 'one_time' | 'recurring' — Tipo de cargo
    - `billing_interval` string, nullable — Intervalo de facturación (para suscripciones)
    - `billing_interval_count` integer, nullable — Cada cuántos intervalos se cobra
    - `periods_before_automatic_cancellation` integer, nullable — Períodos antes de cancelar automáticamente
    - `free_trial_interval` string, nullable — Intervalo del período de prueba
    - `free_trial_interval_count` integer, nullable — Duración del período de prueba
    - `proration_behavior` 'none' | 'create_prorations' — Comportamiento de prorrateo del primer cobro de la suscripción. `create_prorations` cobra solo los días restantes hasta el día de cobro; `none` cobra el monto completo.
    - `billing_cycle_anchor_day` integer, nullable — Día del mes (1–31) en que ocurrirán los cobros recurrentes. Si el mes tiene menos días, se cobra el último día.
    - `defer_to_billing_day` boolean — Si es `true`, la suscripción difiere su primer cobro hasta la próxima ocurrencia de `billing_cycle_anchor_day` (solo se guarda el método de pago al crear).
  - `storefront_link` string — Link público del producto en la tienda
  - `metadata` object, nullable — Metadata personalizada
  - `custom_fields` CheckoutCustomFieldDefinition[] — Definiciones de campos personalizados activos en el checkout.
    - `id` string
    - `key` string — Identificador estable usado en webhooks y la API.
    - `type` 'text' | 'numeric' | 'dropdown'
    - `label` object — Hash con la etiqueta en cada idioma soportado. `_original` es lo que escribió el comerciante; el resto se genera automáticamente.
    - `optional` boolean
    - `minimum_length` integer, nullable
    - `maximum_length` integer, nullable
    - `default_value` string, nullable
    - `options` CheckoutCustomFieldDefinitionOptionsItems[], nullable — Solo para `type: dropdown`.
      - `label` string
      - `value` string

## Other responses

- `400` — Error de validación

---

[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/f494a078482c/schema)