Abonnements clients
Gérez les abonnements récurrents individuels de vos clients.
L’API Customer subscriptions permet de gérer les abonnements de paiement récurrents par client. Un abonnement lie un client à un plan et suit le cycle de vie des prélèvements. Les opérations list / get figurent aussi sous Abonnements selon l’espace de noms du SDK.
Authentification
Authentification par clé API dans l’en-tête `X-API-Key`. L’identifiant marchand est en général déduit de la clé. Voir Authentification.
Objet abonnement client
Représente un abonnement actif ou passé pour un client à un plan donné. Les structures correspondent aux objets renvoyés par l’API ; voir Modèles de données.
Points de terminaison
Lister les abonnements clients
Liste paginée et filtrable des abonnements marchand.
Point de terminaison : `GET /customer-subscriptions`
Paramètres de requête :
| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
merchant_id | string (UUID) | Évent. | Identifiant marchand. (Peut être déduit de la clé) |
customer_id | string (UUID) | Non | Filtrer par client. |
status | string | Non | Statut : `pending`, `active`, `paused`, `cancelled`, `expired`, `past_due`, `trial`. |
limit | number | Non | Nombre max de résultats (défaut : 20). |
offset | number | Non | Décalage pagination (défaut : 0). |
Exemple de réponse (200 OK) :
{
"success": true,
"data": [
{
"subscription_id": "5f8e3c9d-f1b4-4c0a-8e8c-dc56c7e1dde4",
"merchant_id": "904d003c-3736-41d4-90a5-9de74d404fd7",
"organization_id": "0979ec77-9fb1-4c9a-8c55-d7fb6c182c9c",
"plan_id": "129208a9-23a0-4827-83f3-58f5dde344f6",
"plan_name": "Premium Monthly Plan",
"plan_amount": 10000,
"plan_currency_code": "XOF",
"plan_billing_frequency": "monthly",
"customer_id": "7210f6c9-a9c3-4a1e-9d9c-8e8f1e6b2c3d",
"customer_name": "John Doe",
"customer_email": "john.doe@example.com",
"status": "active",
"start_date": "2025-01-01T00:00:00.000Z",
"end_date": null,
"next_billing_date": "2025-02-01T00:00:00.000Z",
"metadata": { "source": "checkout_session" },
"created_at": "2025-01-01T00:00:00.000Z",
"updated_at": "2025-01-01T00:00:00.000Z"
}
],
"meta": {
"limit": 20,
"offset": 0,
"total_returned": 1
}
}Détail d’un abonnement
Point de terminaison : `GET /customer-subscriptions/{subscription_id}`
Paramètres de chemin :
| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
subscription_id | string (UUID) | Oui | Identifiant de l’abonnement (subscription_id). |
Paramètres de requête :
| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
merchant_id | string (UUID) | Évent. | (Peut être déduit de la clé) |
Exemple de réponse (200 OK) :
{
"success": true,
"data": {
"subscription_id": "5f8e3c9d-f1b4-4c0a-8e8c-dc56c7e1dde4",
"updated_at": "2025-01-01T00:00:00.000Z"
}
}Mettre à jour un abonnement
Met à jour statut, dates ou métadonnées.
Point de terminaison : `PATCH /customer-subscriptions/{subscription_id}`
Paramètres de chemin :
| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
subscription_id | string (UUID) | Oui | Identifiant de l’abonnement. |
Paramètres de requête :
| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
merchant_id | string (UUID) | Évent. | (Peut être déduit de la clé) |
Corps de requête — au moins un champ optionnel :
| Paramètre | Type | Description |
|---|---|---|
status | string | Nouveau statut : `active`, `paused`, `cancelled`, `expired`, `past_due`, `trial`. |
start_date | string (ISO8601) | Nouvelle date de début. |
end_date | string (ISO8601) | Nouvelle date de fin (souvent à l’annulation). |
next_billing_date | string (ISO8601) | Prochaine date de facturation manuelle. |
metadata | object | Fusion avec les métadonnées existantes. |
Exemple (pause) :
{
"status": "paused",
"metadata": {
"reason": "Customer request via support ticket #123"
}
}Exemple de réponse (200 OK) :
{
"success": true,
"data": {
"subscription_id": "5f8e3c9d-f1b4-4c0a-8e8c-dc56c7e1dde4",
"status": "paused",
"metadata": {
"source": "checkout_session",
"reason": "Customer request via support ticket #123"
},
"updated_at": "2025-01-15T10:30:00.000Z"
}
}Annuler un abonnement
Passe le statut à `cancelled`.
Point de terminaison : `DELETE /customer-subscriptions/{subscription_id}`
Paramètres de chemin :
| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
subscription_id | string (UUID) | Oui | Identifiant de l’abonnement. |
Paramètres de requête :
| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
merchant_id | string (UUID) | Évent. | (Peut être déduit de la clé) |
Exemple de réponse (200 OK) :
{
"success": true,
"data": {
"subscription_id": "5f8e3c9d-f1b4-4c0a-8e8c-dc56c7e1dde4",
"status": "cancelled",
"end_date": "2025-01-15T11:00:00.000Z",
"updated_at": "2025-01-15T11:00:00.000Z"
}
}Gestion des erreurs
Erreurs courantes : `400 Bad Request` (entrée invalide), `401 Unauthorized`, `404 Not Found` si l’abonnement n’existe pas pour le marchand, `500 Internal Server Error`. Voir Erreurs.