Lister les évènements Stripe du workspace

Renvoie la liste filtrable des évènements Stripe associés à votre workspace, avec un histogramme par type, pour le débogage de facturation.

2 min de lectureTélécharger en PDF

Réponse exemple

{
  "data": [
    {
      "id": "evt_8f2c1a9b-3d4e-4f5a-9b6c-7d8e9f0a1b2c",
      "event_type": "invoice.payment_failed",
      "customer_id": "cus_Qk1lMnOpQrStUv",
      "processed_at": "2026-06-04T08:41:12.330Z",
      "stripe_event_id": "evt_1PqR2sLkdIwHu7ixABCdEfGh",
      "subscription_id": "sub_1PqR2sLkdIwHu7ix9aBcDeFg"
    },
    {
      "id": "evt_1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "event_type": "customer.subscription.updated",
      "customer_id": "cus_Qk1lMnOpQrStUv",
      "processed_at": "2026-06-03T19:02:55.114Z",
      "stripe_event_id": "evt_1PqQ9rLkdIwHu7ixZyXwVuTs",
      "subscription_id": "sub_1PqR2sLkdIwHu7ix9aBcDeFg"
    }
  ],
  "note": "Pass include_raw=true to inspect the full Stripe event payload.",
  "filter": {
    "limit": 50,
    "since": null,
    "event_type": "invoice.payment_failed",
    "include_raw": false
  },
  "object": "list",
  "counts_by_type": [
    {
      "count": 1,
      "event_type": "invoice.payment_failed"
    },
    {
      "count": 1,
      "event_type": "customer.subscription.updated"
    }
  ]
}

GET/v1/billing/stripe-eventsVue cantonnée au workspace des évènements Stripe (facturation, abonnements) reçus par Coffrify.

Cet endpoint expose les évènements Stripe pertinents pour votre workspace uniquement (la requête est systématiquement filtrée sur workspace_id). Il est pensé pour les flux de débogage du type « pourquoi n'ai-je pas reçu cette facture ? » : il liste les évènements de facturation et d'abonnement déjà traités par Coffrify, triés du plus récent au plus ancien (processed_at décroissant). En plus de la liste brute, la réponse inclut un histogramme par type d'évènement (counts_by_type) calculé sur le lot renvoyé, pratique pour repérer d'un coup d'œil une rafale d'échecs de paiement.

Authentification

Requête authentifiée par clé API. Le scope billing:read est requis : une clé qui ne le porte pas reçoit une erreur 403 scope_missing. L'endpoint est classé expensive côté quota (il peut scanner de larges listes), il consomme donc le quota par minute dédié aux endpoints coûteux du workspace.

Paramètres de requête

Paramètre	Type	Requis	Description
limit	entier	Non	Nombre maximum d'évènements renvoyés. Borné côté serveur entre 1 et 200, défaut 50. Une valeur invalide ou hors borne est ramenée dans l'intervalle.
event_type	chaîne	Non	Filtre exact sur le type d'évènement Stripe (ex. `invoice.payment_failed`, `customer.subscription.updated`). Si absent, tous les types sont renvoyés.
since	chaîne (timestamp)	Non	Ne renvoie que les évènements dont `processed_at` est supérieur ou égal à cette valeur (filtre `gte`). Utiliser un horodatage ISO 8601.
include_raw	booléen	Non	Si égal à `true`, ajoute le champ `raw` (charge utile complète de l'évènement Stripe) à chaque entrée. Toute autre valeur est traitée comme `false`.

Réponse

La réponse est un objet de type liste. object vaut "list". data contient le tableau des évènements ; chaque entrée expose id, stripe_event_id, event_type, customer_id, subscription_id, processed_at (et raw uniquement si include_raw=true). filter rappelle les filtres effectivement appliqués (event_type, since, include_raw, limit). counts_by_type est l'histogramme du lot, trié par count décroissant, chaque entrée étant { event_type, count }. note invite à passer include_raw=true pour inspecter la charge utile complète ; il vaut null quand include_raw est déjà actif.

Erreurs

Code	Quand	Résolution
401 missing_api_key	En-tête Authorization absent.	Ajouter `Authorization: Bearer cof_live_...` (ou clé de test / MCP).
401 invalid_api_key	Clé malformée, inconnue ou révoquée par défaut.	Vérifier le préfixe et la validité de la clé dans la console.
403 scope_missing	La clé ne porte pas le scope `billing:read`.	Émettre ou utiliser une clé incluant `billing:read`.
403 ip_not_allowed	L'IP appelante n'est pas dans la liste autorisée de la clé.	Appeler depuis une IP autorisée ou ajuster l'allow-list de la clé.
429 rate_limited	Quota par minute (classe `expensive`) dépassé pour le workspace.	Respecter l'en-tête `Retry-After` et espacer les appels.
500 internal_error	Échec de la requête en base lors de la lecture des évènements.	Réessayer ; si le problème persiste, contacter le support avec le `request_id`.

Voir aussi

GET /v1/billing/subscription — état de l'abonnement courant du workspace.
GET /v1/billing/invoices — historique des factures émises.
GET /v1/audit-logs — journal d'audit pour corréler un évènement de facturation avec une action.