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 ?

UtileÀ améliorer

Schéma de l’objet

ResponseObjet Product

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

jsonCopier

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

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.

POSTCorps de la requête

nameRequis

stringex :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_amountRequis

integercentimesex :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.

currencyRequis

stringISO 4217ex :XAF

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

price_typeRequis

stringdé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.

descriptionOptionnel

string

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

▸En savoir plus

💡

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.

imagesOptionnel

array[url]

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

▸En savoir plus

💡

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.

activeOptionnel

booleandéfaut :true

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

▸En savoir plus

💡

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.

metadataOptionnel

object

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

▸En savoir plus

💡

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 ?

UtileÀ améliorer

Créer un Product

cURLNode JSPythonPHPRuby

bashCopier

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

Le produit est créé et disponible immédiatement pour être attaché à un CheckoutSession ou PaymentLink.

jsonCopier

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

GETParamètres de requête (query)

activeOptionnel

boolean

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

▸En savoir plus

💡

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.

currencyOptionnel

stringISO 4217

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

searchOptionnel

string

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

orderingOptionnel

stringdéfaut :-created_at

Tri. Champs disponibles : created_at, name, unit_amount.

pageOptionnel

integerdéfaut :1

Numéro de page.

page_sizeOptionnel

integerdé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.

PATCHCorps de la mise à jour (PATCH)

nameOptionnel

string

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

unit_amountOptionnel

integercentimes

Nouveau prix unitaire.

▸En savoir plus

💡

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.

activeOptionnel

boolean

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

metadataOptionnel

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 ?

UtileÀ améliorer

Lister les produits actifs

cURLNode JSPython

bashCopier

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

Modifier un produit

cURLNode JSPython

bashCopier

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 mis à jour

jsonCopier

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

cURLNode JSPython

bashCopier

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

Response200 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.

jsonCopier

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