---
title: "Crear un producto"
method: POST
path: "/products"
tags: ["products"]
---

# Crear un producto

`POST /products`

Crea un nuevo producto. Puede ser de pago único o de suscripción. Cada producto puede tener máximo 1 precio.

## Headers

- `X-SECRET-KEY` string, required

## Request body

- object
  - `product` ProductsPostRequestBodyContentApplicationJsonSchemaProduct, required
    - `name` string, required — Nombre del producto
    - `description` string — (Opcional) Descripción del producto
    - `image_url` string — (Opcional) URL de la imagen del producto
    - `success_url` string, uri — (Opcional) URL de redirección después de un pago exitoso
    - `cancel_url` string, uri — (Opcional) URL de redirección cuando el comprador cancela
    - `custom_terms_and_conditions` string — (Opcional) Términos y condiciones personalizados
    - `phone_requirement` 'none' | 'optional' | 'required' — (Opcional) Requerimiento de teléfono
    - `address_requirement` 'none' | 'optional' | 'required' — (Opcional) Requerimiento de dirección
    - `billing_info_requirement` 'none' | 'optional' | 'required' — (Opcional) Requerimiento de información fiscal (NIT)
    - `adjustable_quantity` boolean — (Opcional) Permitir al comprador ajustar la cantidad
    - `inventory_quantity` integer — (Opcional) Cantidad en inventario. Cada compra lo decrementa.
    - `has_dynamic_pricing` boolean — (Opcional) Precio dinámico. El precio se convierte en el 'monto a recibir' neto.
    - `payment_method_types` ProductsPostRequestBodyContentApplicationJsonSchemaProductPaymentMethodTypesItems[] — (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` ProductsPostRequestBodyContentApplicationJsonSchemaProductAvailableInstallmentsItems[] — (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 — (Opcional) Metadata personalizada
    - `custom_fields` CheckoutCustomFieldRequest[] — (Opcional) Hasta 3 campos personalizados a recolectar del comprador al pagar. La etiqueta se traduce automáticamente a los idiomas soportados.
      - `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` ProductsPostRequestBodyContentApplicationJsonSchemaProductPricesAttributesItems[], required — Precios del producto (máximo 1)
      - `amount_in_cents` integer, required — Monto en centavos. El mínimo es 500 para GTQ (Q5) y 100 para USD ($1).
      - `currency` 'GTQ' | 'USD', required — Moneda
      - `charge_type` 'one_time' | 'recurring', required — Tipo de cargo
      - `billing_interval` 'week' | 'month' | 'year' — (Para suscripciones) Intervalo de facturación
      - `billing_interval_count` integer — (Para suscripciones) Cada cuántos intervalos se cobra
      - `periods_before_automatic_cancellation` integer — (Opcional) Períodos antes de cancelar automáticamente
      - `periods_before_allowed_to_cancel` integer — (Opcional) Períodos mínimos antes de que el cliente pueda cancelar
      - `free_trial_interval` 'week' | 'month' | 'year' — (Opcional) Intervalo del período de prueba gratuito
      - `free_trial_interval_count` integer — (Opcional) Duración del período de prueba gratuito
      - `proration_behavior` 'none' | 'create_prorations' — (Opcional, para suscripciones mensuales) Controla el primer cobro cuando la suscripción se crea un día distinto al `billing_cycle_anchor_day`. `create_prorations` cobra solo los días restantes hasta el día de cobro (como ítem de crédito en el checkout); `none` cobra el monto completo. Ignorado si hay período de prueba gratuito.
      - `billing_cycle_anchor_day` integer — (Opcional, para suscripciones mensuales) Día del mes (1–31) en que ocurrirán los cobros recurrentes. Combínalo con `proration_behavior` o `defer_to_billing_day` para controlar la fecha del primer cobro. Si el mes tiene menos días, se cobra el último día.
      - `defer_to_billing_day` boolean — (Opcional, para suscripciones mensuales) Si es `true`, difiere el primer cobro hasta la próxima ocurrencia de `billing_cycle_anchor_day` (solo se guarda el método de pago al crear). Alternativa a `proration_behavior: create_prorations` cuando no quieres cobrar nada hasta el día de cobro.

## Response `201`

Producto creado exitosamente

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