Products

Les objets Product représentent les biens ou services que vous vendez. En associant un Product à un CheckoutSession, un PaymentLink ou une Invoice, vous affichez les détails du produit sur la page de paiement et dans les reçus.

Chaque Product embarque son propre prix (unit_amount + currency). Pour des produits à prix variable ou des dons libres, utilisez price_type: “free”.

Products vs. montant direct

Vous pouvez créer un PaymentIntent avec un amount brut sans Product. Les Products sont recommandés dès que vous souhaitez afficher un nom, une description et une image sur la page de paiement, ou générer des rapports par produit dans votre dashboard.

Endpoints

Méthode	Endpoint	Description
POST	`/products/`	Créer un produit
GET	`/products/`	Lister les produits (paginé, filtrable)
GET	`/products/{id}/`	Récupérer un produit par son ID
PATCH	`/products/{id}/`	Modifier un produit
DELETE	`/products/{id}/`	Archiver un produit (soft delete)

Cette introduction est-elle utile ?

Schéma de l’objet

Response Objet Product

Structure complète retournée par tous les endpoints de cette ressource.

json

{
  "id": "prod_xxxxxxxxxxxx",
  "object": "product",
  "app": "app_xxxxxxxx",
  "name": "Formation Excel Avancé",
  "description": "Maîtrisez Excel pour votre business",
  "images": [
    "https://cdn.sangho.com/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"
}

Créer un Product

Crée un nouveau produit dans votre catalogue. Le produit est immédiatement disponible pour être associé à un CheckoutSession, PaymentLink ou Invoice.

POST Corps de la requête

name Requis

string ex : Formation Excel Avancé

Nom du produit. Visible par l’acheteur sur la page de paiement, dans les reçus et les emails de confirmation.

Max 255 caractères. Choisissez un nom clair et descriptif — c’est la première information que l’acheteur voit avant de payer.

unit_amount Requis

integer centimes ex : 25000

Prix unitaire en centimes. Ignoré si price_type est free.

Même règle que pour les PaymentIntents : exprimez toujours en centimes. 25 000 XAF = 25000. Pour les devises à décimales (USD, EUR), 25 USD = 2500.

currency Requis

string ISO 4217 ex : XAF

Code ISO 4217 de la devise du produit. Doit correspondre à une devise activée sur votre App.

price_type Requis

string défaut : fixed

Détermine si le prix est fixe ou libre. Valeurs : fixed (prix défini par unit_amount) ou free (l’acheteur saisit le montant).

free est idéal pour les dons, le crowdfunding ou les paiements “pay what you want”. Dans ce mode, unit_amount peut servir de montant suggéré affiché à l’acheteur.

description Optionnel

string

Description détaillée du produit. Affichée sous le nom sur la page de paiement et dans les reçus.

Max 2 000 caractères. Texte brut uniquement — pas de HTML. Une bonne description augmente la confiance de l’acheteur et réduit les abandons de paiement.

images Optionnel

array[url]

Liste d’URLs d’images du produit. La première image est utilisée comme image principale sur la page de paiement.

Maximum 8 images. Formats acceptés : JPEG, PNG, WebP. Dimensions recommandées : 800×800 px minimum. Les URLs doivent être publiquement accessibles (HTTPS). Sangho ne stocke pas les images — référencez vos propres URLs CDN.

active Optionnel

boolean défaut : true

Indique si le produit est actif et peut être utilisé dans de nouveaux CheckoutSessions, PaymentLinks ou Invoices.

Désactiver un produit (active: false) ne supprime pas les liens existants — les paiements en cours restent valides. C’est un moyen de retirer un produit du catalogue sans perdre l’historique.

metadata Optionnel

object

Données libres associées au produit — SKU interne, catégorie, référence ERP, etc.

Les métadonnées du Product sont incluses dans les webhooks checkout.completed et payment_intent.succeeded quand un Product est attaché. Pratique pour déclencher des automatisations côté serveur (livraison de licence, activation d’accès, etc.).

Les paramètres de création sont-ils clairs ?

Créer un Product

bash

curl -X POST https://api.sangho.com/v1/products/ \
  -H "Authorization: Bearer sk_live_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" }
  }'

Response 201 Created

Le produit est créé et disponible immédiatement pour être attaché à un CheckoutSession ou 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"
}

Lister les Products

GET Paramètres de requête (query)

active Optionnel

boolean

Filtrer par statut d’activation. true retourne uniquement les produits actifs, false les archivés.

Par défaut (sans ce filtre), tous les produits actifs ET archivés sont retournés. Utilisez active=true pour n’afficher que le catalogue courant à vos clients.

currency Optionnel

string ISO 4217

Filtrer par devise. Utile si votre catalogue couvre plusieurs marchés avec des devises différentes.

search Optionnel

string

Recherche sur le nom et la description du produit. Partielle, insensible à la casse.

ordering Optionnel

string défaut : -created_at

Tri. Champs disponibles : created_at, name, unit_amount.

page Optionnel

integer défaut : 1

Numéro de page.

page_size Optionnel

integer défaut : 20

Résultats par page. Maximum : 100.

Modifier un Product

Modifie les champs d’un Product existant. Le changement de prix ( unit_amount) n’affecte pas les CheckoutSessions ou PaymentLinks déjà créés — seuls les nouveaux utilisent le nouveau prix.

PATCH Corps de la mise à jour (PATCH)

name Optionnel

string

Nouveau nom. Mis à jour sur la page de paiement pour les liens existants non encore payés.

unit_amount Optionnel

integer centimes

Nouveau prix unitaire.

Modifier le prix d’un produit n’affecte pas rétroactivement les sessions de paiement déjà créées. Seuls les nouveaux CheckoutSessions créés après la modification utiliseront le nouveau prix.

active Optionnel

boolean

Activer (true) ou archiver (false) le produit.

metadata Optionnel

object

Fusion des métadonnées existantes.

Archiver un Product

L’endpoint DELETE archive le produit (soft delete) en passant active à false. Le produit reste accessible via l’API mais ne peut plus être attaché à de nouveaux liens.

Soft delete, pas de suppression réelle

Contrairement aux Customers, la suppression d’un Product est réversible. Vous pouvez le réactiver via PATCH { active: true }. Les PaymentLinks et CheckoutSessions existants qui référencent ce produit continuent de fonctionner.

Les opérations sur les Products sont-elles bien documentées ?

Lister les produits actifs

bash

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

Modifier un produit

bash

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

Response 200 OK — Product mis à jour

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"
}

Archiver un produit

bash

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

Response 200 OK — Archivé

Le produit est archivé (active: false). Il reste accessible en lecture mais ne peut plus être attaché à de nouveaux liens.

La suppression d'un Product est réversible via PATCH { active: true }. Les PaymentLinks existants continuent de fonctionner.

json

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