Référence API
URL de base https://api.qbill.dev/v1, en-tête x-api-key. Chaque route ci-dessous accepte une clé secrète ; celles marquées publishable acceptent aussi une clé publishable (lecture seule).
Clients
| Méthode | Chemin | Rôle | Clé |
|---|
POST | /v1/customers | Crée un client. | secret |
GET | /v1/customers | Liste les clients (limit, offset). | secret |
GET | /v1/customers/:id | Récupère un client. | secret |
PATCH | /v1/customers/:id | Modifie un client. | secret |
DELETE | /v1/customers/:id | Supprime un client (suppression logique). | secret |
curl -X POST https://api.qbill.dev/v1/customers \
-H "x-api-key: qb_test_sk_…" \
-H "Content-Type: application/json" \
-d '{"name":"Awa Diop","email":"awa@example.com"}'
Plans
| Méthode | Chemin | Rôle | Clé |
|---|
POST | /v1/plans | Crée un plan. | secret |
GET | /v1/plans | Liste les plans. | secret |
GET | /v1/plans | Liste les plans. | publishable |
GET | /v1/plans/:id | Récupère un plan. | secret |
GET | /v1/plans/:id | Récupère un plan. | publishable |
PATCH | /v1/plans/:id | Modifie un plan. | secret |
DELETE | /v1/plans/:id | Archive un plan. | secret |
POST | /v1/plans/:id/restore | Restaure un plan archivé. | secret |
POST | /v1/plans/:id/clone | Duplique un plan. | secret |
GET | /v1/plans/:id/tiers | Liste les paliers d'un plan. | secret |
GET | /v1/plans/:id/tiers | Liste les paliers d'un plan. | publishable |
PUT | /v1/plans/:id/tiers | Remplace les paliers d'un plan. | secret |
GET | /v1/plans/:id/price-components | Liste les composantes de prix d'un plan. | secret |
GET | /v1/plans/:id/price-components | Liste les composantes de prix d'un plan. | publishable |
POST | /v1/plans/:id/price-components | Ajoute une composante de prix. | secret |
PATCH | /v1/plans/:id/price-components/:componentId | Modifie une composante de prix. | secret |
DELETE | /v1/plans/:id/price-components/:componentId | Supprime une composante de prix. | secret |
curl -X POST https://api.qbill.dev/v1/plans \
-H "x-api-key: qb_test_sk_…" \
-H "Content-Type: application/json" \
-d '{"name":"Pro","pricing_model":"flat_rate","amount_monthly":15000}'
Abonnements
| Méthode | Chemin | Rôle | Clé |
|---|
POST | /v1/subscriptions | Crée un abonnement. | secret |
GET | /v1/subscriptions | Liste les abonnements. | secret |
GET | /v1/subscriptions/:id | Récupère un abonnement. | secret |
POST | /v1/subscriptions/:id/cancel | Résilie immédiatement. | secret |
POST | /v1/subscriptions/:id/pause | Met en pause (resume_at optionnel). | secret |
POST | /v1/subscriptions/:id/resume | Reprend un abonnement en pause. | secret |
POST | /v1/subscriptions/:id/change-plan | Change de plan ou de quantité. | secret |
DELETE | /v1/subscriptions/:id/pending-change | Annule un changement de plan différé. | secret |
POST | /v1/subscriptions/:id/reactivate | Réactive un abonnement. | secret |
POST | /v1/subscriptions/:id/extend-trial | Prolonge l'essai. | secret |
POST | /v1/subscriptions/:id/billing-interval | Change l'intervalle de facturation. | secret |
POST | /v1/subscriptions/:id/promotion-code | Applique un code promotionnel. | secret |
DELETE | /v1/subscriptions/:id/promotion-code | Retire le code promotionnel. | secret |
GET | /v1/subscriptions/:id/upcoming-invoice | Aperçu de la prochaine facture. | secret |
GET | /v1/subscriptions/:id/addons | Liste les add-ons de l'abonnement. | secret |
POST | /v1/subscriptions/:id/addons | Ajoute un add-on à l'abonnement. | secret |
PATCH | /v1/subscriptions/:id/addons/:addonId | Modifie un add-on de l'abonnement. | secret |
DELETE | /v1/subscriptions/:id/addons/:addonId | Retire un add-on de l'abonnement. | secret |
curl -X POST https://api.qbill.dev/v1/subscriptions \
-H "x-api-key: qb_test_sk_…" \
-H "Content-Type: application/json" \
-d '{"customer":"<customer_id>","plan":"<plan_id>","billing_interval":"monthly"}'
Factures
| Méthode | Chemin | Rôle | Clé |
|---|
POST | /v1/invoices | Crée une facture ponctuelle. | secret |
GET | /v1/invoices | Liste les factures. | secret |
GET | /v1/invoices/:id | Récupère une facture. | secret |
GET | /v1/invoices/:id/pdf | Télécharge le PDF. | secret |
POST | /v1/invoices/:id/finalize | Finalise un brouillon. | secret |
POST | /v1/invoices/:id/void | Annule une facture (brouillon, ouverte ou échouée). | secret |
POST | /v1/invoices/:id/resend | Renvoie la facture par e-mail. | secret |
curl -X POST https://api.qbill.dev/v1/invoices \
-H "x-api-key: qb_test_sk_…" \
-H "Content-Type: application/json" \
-d '{"customer":"<customer_id>","amount":25000,"description":"Setup fee","due_date":"2026-11-01","status":"open"}'
Paiements
| Méthode | Chemin | Rôle | Clé |
|---|
POST | /v1/payments/initiate | Lance le paiement d'une facture et renvoie redirectUrl. | secret |
curl -X POST https://api.qbill.dev/v1/payments/initiate \
-H "x-api-key: qb_test_sk_…" \
-H "Content-Type: application/json" \
-d '{"invoice_id":"<invoice_id>","phone_number":"+221770000000","provider":"wave"}'
Remboursements
| Méthode | Chemin | Rôle | Clé |
|---|
POST | /v1/refunds | Rembourse en totalité une facture payée. | secret |
GET | /v1/refunds | Liste les avoirs. | secret |
curl -X POST https://api.qbill.dev/v1/refunds \
-H "x-api-key: qb_test_sk_…" \
-H "Content-Type: application/json" \
-d '{"invoice_id":"<invoice_id>","reason":"Duplicate charge"}'
Consommation
| Méthode | Chemin | Rôle | Clé |
|---|
POST | /v1/usage | Enregistre une consommation. | secret |
GET | /v1/usage | Liste la consommation d'un abonnement (?subscription=). | secret |
GET | /v1/usage/alerts | Alertes de seuil récentes (80 % et 100 %). | secret |
curl -X POST https://api.qbill.dev/v1/usage \
-H "x-api-key: qb_test_sk_…" \
-H "Content-Type: application/json" \
-d '{"subscription":"<subscription_id>","metric_name":"api_calls","quantity":120,"idempotency_key":"batch-2026-10-04"}'
Webhooks
| Méthode | Chemin | Rôle | Clé |
|---|
POST | /v1/webhooks | Crée un endpoint de webhook. | secret |
GET | /v1/webhooks | Liste les endpoints. | secret |
GET | /v1/webhooks/events | Liste les événements disponibles. | secret |
PATCH | /v1/webhooks/:id | Modifie un endpoint (url, events, status). | secret |
DELETE | /v1/webhooks/:id | Supprime un endpoint. | secret |
POST | /v1/webhooks/:id/test | Envoie un événement webhook.test. | secret |
GET | /v1/webhooks/:id/deliveries | Liste les livraisons d'un endpoint. | secret |
POST | /v1/webhooks/:id/deliveries/:deliveryId/retry | Rejoue une livraison. | secret |
curl -X POST https://api.qbill.dev/v1/webhooks \
-H "x-api-key: qb_test_sk_…" \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com/qbill","events":["invoice.paid"]}'
Add-ons
| Méthode | Chemin | Rôle | Clé |
|---|
GET | /v1/addons | Liste les add-ons. | secret |
GET | /v1/addons/:id | Récupère un add-on. | secret |
POST | /v1/addons | Crée un add-on. | secret |
PATCH | /v1/addons/:id | Modifie un add-on. | secret |
DELETE | /v1/addons/:id | Retire un add-on de la vente. | secret |
POST | /v1/addons/:id/restore | Remet un add-on en vente. | secret |
curl -X POST https://api.qbill.dev/v1/addons \
-H "x-api-key: qb_test_sk_…" \
-H "Content-Type: application/json" \
-d '{"name":"Extra seats","price_monthly":5000}'
Coupons
| Méthode | Chemin | Rôle | Clé |
|---|
GET | /v1/coupons | Liste les coupons. | secret |
POST | /v1/coupons | Crée un coupon. | secret |
PATCH | /v1/coupons/:id | Modifie un coupon. | secret |
DELETE | /v1/coupons/:id | Supprime un coupon. | secret |
curl -X POST https://api.qbill.dev/v1/coupons \
-H "x-api-key: qb_test_sk_…" \
-H "Content-Type: application/json" \
-d '{"name":"Launch","type":"percentage","value":20,"duration":"repeating","duration_in_periods":3}'
| Méthode | Chemin | Rôle | Clé |
|---|
GET | /v1/promotion-codes | Liste les codes promotionnels. | secret |
POST | /v1/promotion-codes | Crée un code promotionnel. | secret |
PATCH | /v1/promotion-codes/:id | Modifie un code promotionnel. | secret |
DELETE | /v1/promotion-codes/:id | Supprime un code promotionnel. | secret |
curl -X POST https://api.qbill.dev/v1/promotion-codes \
-H "x-api-key: qb_test_sk_…" \
-H "Content-Type: application/json" \
-d '{"code":"LAUNCH20","coupon":"<coupon_id>"}'
Liens de vente
| Méthode | Chemin | Rôle | Clé |
|---|
POST | /v1/sales-links | Crée un lien de vente. | secret |
GET | /v1/sales-links | Liste les liens de vente. | secret |
GET | /v1/sales-links/:id | Récupère un lien de vente. | secret |
GET | /v1/sales-links/:id/checkouts | Liste les ventes passées par ce lien. | secret |
POST | /v1/sales-links/:id/deactivate | Désactive le lien. | secret |
POST | /v1/sales-links/:id/activate | Réactive le lien. | secret |
curl -X POST https://api.qbill.dev/v1/sales-links \
-H "x-api-key: qb_test_sk_…" \
-H "Content-Type: application/json" \
-d '{"kind":"plan","title":"Pro plan","plan_id":"<plan_id>","billing_interval":"monthly"}'