Products

Los objetos Product representan los bienes o servicios que usted vende. Al asociar un Product a una CheckoutSession, a un PaymentLink o a una Invoice, muestra los detalles del producto en la página de pago y en los recibos.

Cada Product incorpora su propio precio (unit_amount + currency). Para productos de precio variable o donaciones libres, utilice price_type: “free”.

Products frente a importe directo

Puede crear un PaymentIntent con un amount en bruto sin Product. Los Products se recomiendan en cuanto desee mostrar un nombre, una descripción y una imagen en la página de pago, o generar informes por producto en su panel.

Endpoints

Méthode	Endpoint	Description
POST	`/products/`	Crear un producto
GET	`/products/`	Listar los productos (paginado, filtrable)
GET	`/products/{id}/`	Recuperar un producto por su ID
PATCH	`/products/{id}/`	Modificar un producto
DELETE	`/products/{id}/`	Archivar un producto (soft delete)

¿Le resulta útil esta introducción?

Esquema del objeto

ResponseObjeto Product

Estructura completa devuelta por todos los endpoints de este recurso.

json

{
  "id": "prod_xxxxxxxxxxxx",
  "object": "product",
  "app": "app_xxxxxxxx",
  "name": "Formation Excel Avancé",
  "description": "Maîtrisez Excel pour votre business",
  "images": [
    "https://cdn.sangho.ga/products/excel.jpg"
  ],
  "unit_amount": 25000,
  "currency": "XAF",
  "price_type": "fixed",
  "active": true,
  "metadata": {
    "sku": "FORM-XLS-001",
    "category": "formation"
  },
  "livemode": true,
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z"
}

Crear un Product

Crea un nuevo producto en su catálogo. El producto está disponible de inmediato para asociarlo a una CheckoutSession, un PaymentLink o una Invoice.

POSTCuerpo de la solicitud

nameRequis

stringex :Curso de Excel avanzado

Nombre del producto. Visible para el comprador en la página de pago, en los recibos y en los correos de confirmación.

Máx. 255 caracteres. Elija un nombre claro y descriptivo: es la primera información que ve el comprador antes de pagar.

unit_amountRequis

integercentimesex :25000

Precio unitario en céntimos. Se ignora si price_type es free.

La misma regla que para los PaymentIntents: exprese siempre en céntimos. 25 000 XAF = 25000. Para las monedas con decimales (USD, EUR), 25 USD = 2500.

currencyRequis

stringISO 4217ex :XAF

Código ISO 4217 de la moneda del producto. Debe corresponder a una moneda activada en su App.

price_typeRequis

stringdéfaut :fixed

Determina si el precio es fijo o libre. Valores: fixed (precio definido por unit_amount) o free (el comprador introduce el importe).

free es ideal para donaciones, crowdfunding o pagos de tipo “pay what you want”. En este modo, unit_amount puede servir como importe sugerido que se muestra al comprador.

descriptionOptionnel

string

Descripción detallada del producto. Se muestra bajo el nombre en la página de pago y en los recibos.

Máx. 2 000 caracteres. Solo texto sin formato: nada de HTML. Una buena descripción aumenta la confianza del comprador y reduce los abandonos de pago.

imagesOptionnel

array[url]

Lista de URL de imágenes del producto. La primera imagen se utiliza como imagen principal en la página de pago.

Máximo 8 imágenes. Formatos aceptados: JPEG, PNG, WebP. Dimensiones recomendadas: 800×800 px como mínimo. Las URL deben ser accesibles públicamente (HTTPS). Sangho no almacena las imágenes: haga referencia a sus propias URL de CDN.

activeOptionnel

booleandéfaut :true

Indica si el producto está activo y puede utilizarse en nuevas CheckoutSessions, PaymentLinks o Invoices.

Desactivar un producto (active: false) no elimina los enlaces existentes: los pagos en curso siguen siendo válidos. Es una forma de retirar un producto del catálogo sin perder el historial.

metadataOptionnel

object

Datos libres asociados al producto: SKU interno, categoría, referencia de ERP, etc.

Los metadatos del Product se incluyen en los webhooks checkout.completed y payment_intent.succeeded cuando hay un Product asociado. Práctico para activar automatizaciones en el servidor (entrega de licencias, activación de accesos, etc.).

¿Están claros los parámetros de creación?

Crear un Product

bash

curl -X POST https://api.sangho.ga/v1/products/ \
  -H "Authorization: Bearer sk_prod_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Formation Excel Avancé",
    "description": "Maîtrisez Excel pour votre business",
    "unit_amount": 25000,
    "currency": "XAF",
    "price_type": "fixed",
    "images": ["https://cdn.exemple.com/excel.jpg"],
    "metadata": { "sku": "FORM-XLS-001" }
  }'

Response201 Created

El producto se crea y está disponible de inmediato para asociarlo a una CheckoutSession o un PaymentLink.

json

{
  "id": "prod_xxxxxxxxxxxx",
  "object": "product",
  "name": "Formation Excel Avancé",
  "description": "Maîtrisez Excel pour votre business",
  "images": ["https://cdn.exemple.com/excel.jpg"],
  "unit_amount": 25000,
  "currency": "XAF",
  "price_type": "fixed",
  "active": true,
  "metadata": { "sku": "FORM-XLS-001" },
  "livemode": true,
  "created_at": "2026-03-01T10:00:00Z"
}

Listar los Products

GETParámetros de consulta (query)

activeOptionnel

boolean

Filtrar por estado de activación. true devuelve únicamente los productos activos y false los archivados.

Por defecto (sin este filtro), se devuelven todos los productos activos Y archivados. Utilice active=true para mostrar a sus clientes únicamente el catálogo vigente.

currencyOptionnel

stringISO 4217

Filtrar por moneda. Útil si su catálogo abarca varios mercados con monedas distintas.

searchOptionnel

string

Búsqueda en el nombre y la descripción del producto. Parcial e insensible a mayúsculas y minúsculas.

orderingOptionnel

stringdéfaut :-created_at

Ordenación. Campos disponibles: created_at, name, unit_amount.

pageOptionnel

integerdéfaut :1

Número de página.

page_sizeOptionnel

integerdéfaut :20

Resultados por página. Máximo: 100.

Modificar un Product

Modifica los campos de un Product existente. El cambio de precio ( unit_amount) no afecta a las CheckoutSessions ni a los PaymentLinks ya creados: solo los nuevos utilizan el nuevo precio.

PATCHCuerpo de la actualización (PATCH)

nameOptionnel

string

Nuevo nombre. Se actualiza en la página de pago de los enlaces existentes que aún no se hayan pagado.

unit_amountOptionnel

integercentimes

Nuevo precio unitario.

Modificar el precio de un producto no afecta retroactivamente a las sesiones de pago ya creadas. Solo las nuevas CheckoutSessions creadas después de la modificación utilizarán el nuevo precio.

activeOptionnel

boolean

Activar (true) o archivar (false) el producto.

metadataOptionnel

object

Combinación con los metadatos existentes.

Archivar un Product

El endpoint DELETE archiva el producto (soft delete) pasando active a false. El producto sigue siendo accesible mediante la API, pero ya no se puede asociar a nuevos enlaces.

Soft delete, no una eliminación real

A diferencia de los Customers, la eliminación de un Product es reversible. Puede reactivarlo mediante PATCH { active: true }. Los PaymentLinks y las CheckoutSessions existentes que hacen referencia a este producto siguen funcionando.

¿Están bien documentadas las operaciones sobre los Products?

Listar los productos activos

bash

curl "https://api.sangho.ga/v1/products/?active=true&currency=XAF" \
  -H "Authorization: Bearer sk_prod_xxxx"

Modificar un producto

bash

curl -X PATCH https://api.sangho.ga/v1/products/prod_xxx/ \
  -H "Authorization: Bearer sk_prod_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "unit_amount": 30000,
    "metadata": { "sku": "FORM-XLS-002", "promotion": null }
  }'

Response200 OK — Product actualizado

json

{
  "id": "prod_xxxxxxxxxxxx",
  "object": "product",
  "name": "Formation Excel Avancé",
  "unit_amount": 30000,
  "currency": "XAF",
  "active": true,
  "metadata": { "sku": "FORM-XLS-002" },
  "updated_at": "2026-03-15T09:00:00Z"
}

Archivar un producto

bash

curl -X DELETE https://api.sangho.ga/v1/products/prod_xxx/ \
  -H "Authorization: Bearer sk_prod_xxxx"

Response200 OK — Archivado

El producto queda archivado (active: false). Sigue siendo accesible en lectura, pero ya no se puede asociar a nuevos enlaces.

La eliminación de un Product es reversible mediante PATCH { active: true }. Los PaymentLinks existentes siguen funcionando.

json

{
  "id": "prod_xxxxxxxxxxxx",
  "active": false,
  "updated_at": "2026-03-20T12:00:00Z"
}