API reference

Base URL https://api.qbill.dev/v1, header x-api-key. Every route below takes a secret key; the routes marked publishable also accept a publishable key (read-only).

Customers

Method	Path	Purpose	Key
`POST`	`/v1/customers`	Create a customer.	secret
`GET`	`/v1/customers`	List customers (limit, offset).	secret
`GET`	`/v1/customers/:id`	Retrieve a customer.	secret
`PATCH`	`/v1/customers/:id`	Update a customer.	secret
`DELETE`	`/v1/customers/:id`	Delete a customer (soft delete).	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

Method	Path	Purpose	Key
`POST`	`/v1/plans`	Create a plan.	secret
`GET`	`/v1/plans`	List plans.	secret
`GET`	`/v1/plans`	List plans.	publishable
`GET`	`/v1/plans/:id`	Retrieve a plan.	secret
`GET`	`/v1/plans/:id`	Retrieve a plan.	publishable
`PATCH`	`/v1/plans/:id`	Update a plan.	secret
`DELETE`	`/v1/plans/:id`	Archive a plan.	secret
`POST`	`/v1/plans/:id/restore`	Restore an archived plan.	secret
`POST`	`/v1/plans/:id/clone`	Clone a plan.	secret
`GET`	`/v1/plans/:id/tiers`	List a plan's tiers.	secret
`GET`	`/v1/plans/:id/tiers`	List a plan's tiers.	publishable
`PUT`	`/v1/plans/:id/tiers`	Replace a plan's tiers.	secret
`GET`	`/v1/plans/:id/price-components`	List a plan's price components.	secret
`GET`	`/v1/plans/:id/price-components`	List a plan's price components.	publishable
`POST`	`/v1/plans/:id/price-components`	Add a price component.	secret
`PATCH`	`/v1/plans/:id/price-components/:componentId`	Update a price component.	secret
`DELETE`	`/v1/plans/:id/price-components/:componentId`	Delete a price component.	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}'

Subscriptions

Method	Path	Purpose	Key
`POST`	`/v1/subscriptions`	Create a subscription.	secret
`GET`	`/v1/subscriptions`	List subscriptions.	secret
`GET`	`/v1/subscriptions/:id`	Retrieve a subscription.	secret
`POST`	`/v1/subscriptions/:id/cancel`	Cancel immediately.	secret
`POST`	`/v1/subscriptions/:id/pause`	Pause (optional resume_at).	secret
`POST`	`/v1/subscriptions/:id/resume`	Resume a paused subscription.	secret
`POST`	`/v1/subscriptions/:id/change-plan`	Change plan or quantity.	secret
`DELETE`	`/v1/subscriptions/:id/pending-change`	Cancel a deferred plan change.	secret
`POST`	`/v1/subscriptions/:id/reactivate`	Reactivate a subscription.	secret
`POST`	`/v1/subscriptions/:id/extend-trial`	Extend the trial.	secret
`POST`	`/v1/subscriptions/:id/billing-interval`	Change the billing interval.	secret
`POST`	`/v1/subscriptions/:id/promotion-code`	Apply a promotion code.	secret
`DELETE`	`/v1/subscriptions/:id/promotion-code`	Remove the promotion code.	secret
`GET`	`/v1/subscriptions/:id/upcoming-invoice`	Preview the upcoming invoice.	secret
`GET`	`/v1/subscriptions/:id/addons`	List the subscription's add-ons.	secret
`POST`	`/v1/subscriptions/:id/addons`	Add an add-on to the subscription.	secret
`PATCH`	`/v1/subscriptions/:id/addons/:addonId`	Update a subscription add-on.	secret
`DELETE`	`/v1/subscriptions/:id/addons/:addonId`	Remove a subscription add-on.	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"}'

Invoices

Method	Path	Purpose	Key
`POST`	`/v1/invoices`	Create a one-off invoice.	secret
`GET`	`/v1/invoices`	List invoices.	secret
`GET`	`/v1/invoices/:id`	Retrieve an invoice.	secret
`GET`	`/v1/invoices/:id/pdf`	Download the PDF.	secret
`POST`	`/v1/invoices/:id/finalize`	Finalize a draft.	secret
`POST`	`/v1/invoices/:id/void`	Void a draft, open or failed invoice.	secret
`POST`	`/v1/invoices/:id/resend`	Resend the invoice by email.	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"}'

Payments

Method	Path	Purpose	Key
`POST`	`/v1/payments/initiate`	Start paying an invoice and return 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"}'

Refunds

Method	Path	Purpose	Key
`POST`	`/v1/refunds`	Fully refund a paid invoice.	secret
`GET`	`/v1/refunds`	List credit notes.	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"}'

Usage

Method	Path	Purpose	Key
`POST`	`/v1/usage`	Record usage.	secret
`GET`	`/v1/usage`	List a subscription's usage (?subscription=).	secret
`GET`	`/v1/usage/alerts`	Recent threshold alerts (80% and 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

Method	Path	Purpose	Key
`POST`	`/v1/webhooks`	Create a webhook endpoint.	secret
`GET`	`/v1/webhooks`	List endpoints.	secret
`GET`	`/v1/webhooks/events`	List the available events.	secret
`PATCH`	`/v1/webhooks/:id`	Update an endpoint (url, events, status).	secret
`DELETE`	`/v1/webhooks/:id`	Delete an endpoint.	secret
`POST`	`/v1/webhooks/:id/test`	Send a webhook.test event.	secret
`GET`	`/v1/webhooks/:id/deliveries`	List an endpoint's deliveries.	secret
`POST`	`/v1/webhooks/:id/deliveries/:deliveryId/retry`	Retry a delivery.	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

Method	Path	Purpose	Key
`GET`	`/v1/addons`	List add-ons.	secret
`GET`	`/v1/addons/:id`	Retrieve an add-on.	secret
`POST`	`/v1/addons`	Create an add-on.	secret
`PATCH`	`/v1/addons/:id`	Update an add-on.	secret
`DELETE`	`/v1/addons/:id`	Take an add-on off sale.	secret
`POST`	`/v1/addons/:id/restore`	Put an add-on back on sale.	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

Method	Path	Purpose	Key
`GET`	`/v1/coupons`	List coupons.	secret
`POST`	`/v1/coupons`	Create a coupon.	secret
`PATCH`	`/v1/coupons/:id`	Update a coupon.	secret
`DELETE`	`/v1/coupons/:id`	Delete a 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}'

Promotion codes

Method	Path	Purpose	Key
`GET`	`/v1/promotion-codes`	List promotion codes.	secret
`POST`	`/v1/promotion-codes`	Create a promotion code.	secret
`PATCH`	`/v1/promotion-codes/:id`	Update a promotion code.	secret
`DELETE`	`/v1/promotion-codes/:id`	Delete a promotion code.	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>"}'

Sales links

Method	Path	Purpose	Key
`POST`	`/v1/sales-links`	Create a sales link.	secret
`GET`	`/v1/sales-links`	List sales links.	secret
`GET`	`/v1/sales-links/:id`	Retrieve a sales link.	secret
`GET`	`/v1/sales-links/:id/checkouts`	List the sales made through this link.	secret
`POST`	`/v1/sales-links/:id/deactivate`	Deactivate the link.	secret
`POST`	`/v1/sales-links/:id/activate`	Reactivate the link.	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"}'