Listar productos

GET

https://app.recurrente.com/api/products

GET

/api/products

curl https://app.recurrente.com/api/products \
     -H "X-SECRET-KEY: <apiKey>"

200Retrieved

[
  {
    "id": "prod_9lstwgbr",
    "status": "active",
    "tax_category": "good",
    "name": "El nombre de tu producto",
    "description": "string",
    "success_url": "string",
    "cancel_url": "string",
    "custom_terms_and_conditions": "string",
    "phone_requirement": "optional",
    "address_requirement": "none",
    "billing_info_requirement": "optional",
    "has_dynamic_pricing": false,
    "payment_method_types": [
      "card",
      "bank_transfer"
    ],
    "available_installments": [
      3,
      6
    ],
    "inventory_quantity": 12,
    "low_stock_threshold": 3,
    "prices": [
      {
        "id": "price_rky4dog7",
        "status": "active",
        "amount_in_cents": 500,
        "currency": "GTQ",
        "charge_type": "one_time",
        "billing_interval": "month",
        "billing_interval_count": 1,
        "periods_before_automatic_cancellation": 1,
        "free_trial_interval": "string",
        "free_trial_interval_count": 1,
        "proration_behavior": "none",
        "billing_cycle_anchor_day": 1,
        "defer_to_billing_day": true
      }
    ],
    "storefront_link": "https://app.recurrente.com/s/surf-office/el-nombre-de-tu-producto",
    "metadata": {},
    "custom_fields": [
      {
        "id": "ccf_xxxxxxxxxxxx",
        "key": "engraving",
        "type": "text",
        "label": {
          "_original": "Mensaje de grabado",
          "en": "Engraving message",
          "es": "Mensaje de grabado"
        },
        "optional": false,
        "minimum_length": 1,
        "maximum_length": 1,
        "default_value": "string",
        "options": [
          {
            "label": "string",
            "value": "string"
          }
        ]
      }
    ],
    "options": [
      {
        "name": "Talla",
        "values": [
          "S",
          "M",
          "L"
        ]
      }
    ],
    "variants": [
      {
        "id": "var_9lstwgbr",
        "product_id": "prod_9lstwgbr",
        "status": "active",
        "title": "M / Rojo",
        "option_values": [
          "M",
          "Rojo"
        ],
        "sku": "string",
        "price_id": "price_3kd9sla2",
        "amount_in_cents": 12500,
        "currency": "GTQ",
        "inventory_quantity": 1,
        "low_stock_threshold": 3
      }
    ]
  }
]

Lista todos los productos activos de tu cuenta con paginación.

Authentication

X-SECRET-KEYstring

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.

La llave también fija el ambiente: una sk_test_ solo lista y resuelve objetos de prueba (live_mode: false) y una sk_live_ solo objetos reales. Un ID del otro ambiente responde 404 (401 en /customers).

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.

Query parameters

pageintegerOptional>=1Defaults to 1

Número de página (empezando en 1)

itemsintegerOptional1-100Defaults to 10

Elementos por página

Response

Lista de productos

idstringOptional

ID único del producto

statusstringOptional

Estado del producto

tax_categoryenumOptionalDefaults to good

Clasificación para FEL: good (bien) o service (servicio). Cada ítem conserva su clasificación en facturas mixtas. El comercio también puede elegirla en el panel, en Opciones avanzadas del producto.

Allowed values:

namestringOptional

Nombre del producto

descriptionstring or nullOptional

Descripción del producto

success_urlstring or nullOptional

URL de redirección después de un pago exitoso

cancel_urlstring or nullOptional

URL de redirección cuando el comprador cancela

custom_terms_and_conditionsstring or nullOptional

Términos y condiciones personalizados

phone_requirementenumOptionalDefaults to optional

Requerimiento de teléfono

Allowed values:

address_requirementenumOptionalDefaults to none

Requerimiento de dirección

Allowed values:

billing_info_requirementenumOptionalDefaults to optional

Requerimiento de información fiscal

Allowed values:

has_dynamic_pricingbooleanOptional

Si usa precio dinámico

payment_method_typeslist of enumsOptional

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), akisi (efectivo en Akisí; solo cuentas habilitadas, cobros únicos en GTQ con precio fijo y cuentas fuera de Sandbox). Las cuotas se exponen por separado en available_installments.

Allowed values:

available_installmentslist of integersOptional

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.

inventory_quantityinteger or nullOptional

Unidades en existencia. null cuando el producto no lleva inventario (disponibilidad ilimitada). Baja con cada venta pagada y puede quedar en negativo si se vendió más de lo que había. Enviarlo en un PUT registra la diferencia como un ajuste en el historial del producto. Un producto con variantes no lleva conteo propio: cada variante lleva el suyo y el del producto queda en null.

low_stock_thresholdinteger or nullOptional

Desde qué cantidad se considera bajo el inventario de este producto. null usa el valor por defecto de la cuenta.

priceslist of objectsOptional

Precios del producto

storefront_linkstringOptional

Link público del producto en la tienda

metadatamap from strings to strings or nullOptional

Metadata personalizada

custom_fieldslist of objectsOptional

Definiciones de campos personalizados activos en el checkout.

optionslist of objectsOptional

Las opciones en que viene el producto (talla, color…), en orden. Vacío si el producto no tiene variantes.

variantslist of objectsOptional

Las variantes activas del producto, una por combinación de valores. Cada una tiene su propio price_id: úsalo en items[].price_id al crear un checkout para vender esa variante.