API reference

A REST API over HTTPS with predictable resources and JSON responses. Every operation a key can call has a page here, generated from the OpenAPI document the API itself publishes.

Conventions

Resource URLs are plural and stable. Writes take JSON. Amounts are integers in the smallest currency unit, and timestamps are Unix seconds in UTC.

shell

curl https://api.billkit.eu/v1/subscriptions/sub_1Nk9Yz2eZvKp \
  -H "Authorization: Bearer $BILLKIT_SECRET_KEY"

curl https://api.billkit.eu/v1/subscriptions/sub_1Nk9Yz2eZvKp \
  -H "Authorization: Bearer $BILLKIT_SECRET_KEY"

Pagination

List endpoints are cursor-based. Pass limit and page with starting_after, which takes the last id you saw. Responses carry has_more; never infer the end of a list from a short page. Paging is forward-only, so walk backwards by holding on to the cursors you have already used.

Versioning

There is one live version of the API. Requests carry no version header and accounts are not pinned to a dated version, so a change to the API is a change for every caller at once.

The date on this site, 2026-09-13, is the day the OpenAPI document behind these pages was taken. It dates the document, not your account, and there is nothing to send it in.

Resources

90 operations, every one of them reachable with an API key. Each has its own page, generated from the OpenAPI document and its required scope. To filter the whole surface in one view, use the explorer.

Customers

People and organisations you bill.

Operation	Endpoint
List customers	GET /v1/customers
Create a customer	POST /v1/customers
Delete customer	DELETE /v1/customers/{customer_id}
Retrieve a customer	GET /v1/customers/{customer_id}
Update customer	POST /v1/customers/{customer_id}
Purge customer	POST /v1/customers/{customer_id}/purge
Set customer VAT number	POST /v1/customers/{customer_id}/vat_number

Products

The things you sell, independent of what they cost.

Operation	Endpoint
List products	GET /v1/products
Create product	POST /v1/products
Get product	GET /v1/products/{product_id}
Update product	POST /v1/products/{product_id}

Prices

Amount, currency, interval and tax behaviour for a product.

Operation	Endpoint
List prices	GET /v1/prices
Create price	POST /v1/prices
Get price	GET /v1/prices/{price_id}
Update price	POST /v1/prices/{price_id}

Subscriptions

Recurring agreements between a customer and a price.

Operation	Endpoint
List subscriptions	GET /v1/subscriptions
Retrieve a subscription	GET /v1/subscriptions/{subscription_id}
Cancel a subscription	POST /v1/subscriptions/{subscription_id}/cancel
Pause subscription	POST /v1/subscriptions/{subscription_id}/pause
Preview update subscription	POST /v1/subscriptions/{subscription_id}/preview_update
Reactivate subscription	POST /v1/subscriptions/{subscription_id}/reactivate
Reauthorize payment method	POST /v1/subscriptions/{subscription_id}/reauthorize_payment_method
Resume subscription	POST /v1/subscriptions/{subscription_id}/resume
Change a subscription's plan	POST /v1/subscriptions/{subscription_id}/update

Checkout

Hosted and embedded payment sessions, and saved payment methods.

Operation	Endpoint
Create one-shot payment	POST /v1/checkout/one_shot
Get one-shot payment	GET /v1/checkout/one_shot/{one_shot_id}
Create a Checkout session	POST /v1/checkout/sessions
Get checkout session	GET /v1/checkout/sessions/{checkout_id}

Usage records

Metered events reported against a subscription.

Operation	Endpoint
List usage records	GET /v1/subscriptions/{subscription_id}/usage_records
Create usage record	POST /v1/subscriptions/{subscription_id}/usage_records
Get usage summary	GET /v1/subscriptions/{subscription_id}/usage_summary

Invoices

Statements generated at the end of a billing period.

Operation	Endpoint
List invoices	GET /v1/invoices
Get invoice	GET /v1/invoices/{invoice_id}
Email invoice	POST /v1/invoices/{invoice_id}/email
Get invoice PDF	GET /v1/invoices/{invoice_id}/pdf
Void invoice route	POST /v1/invoices/{invoice_id}/void

Credit notes

Reversals issued against an invoice.

Operation	Endpoint
List credit notes	GET /v1/credit_notes
Get credit note	GET /v1/credit_notes/{credit_note_id}
Get credit note PDF	GET /v1/credit_notes/{credit_note_id}/pdf

Payments

Individual charge attempts and their outcome.

Operation	Endpoint
List payments	GET /v1/payments
Get payment	GET /v1/payments/{payment_id}
Get payment provider payload	GET /v1/payments/{payment_id}/provider

Refunds

Full and partial returns against a settled payment.

Operation	Endpoint
List refunds	GET /v1/refunds
Create refund	POST /v1/refunds
Get refund	GET /v1/refunds/{refund_id}

Disputes

Chargebacks raised by the cardholder or their bank.

Operation	Endpoint
List disputes	GET /v1/disputes
Get dispute	GET /v1/disputes/{dispute_id}

Coupons

Percentage and fixed-amount discounts applied at checkout.

Operation	Endpoint
List coupons	GET /v1/coupons
Create coupon	POST /v1/coupons
Get coupon	GET /v1/coupons/{coupon_id}
Update coupon	POST /v1/coupons/{coupon_id}
Validate coupon	POST /v1/coupons/validate

Tax rates

VAT and sales-tax rates applied to a line item.

Operation	Endpoint
List tax rates	GET /v1/tax_rates
Create tax rate	POST /v1/tax_rates
Get tax rate	GET /v1/tax_rates/{tax_rate_id}
Update tax rate	POST /v1/tax_rates/{tax_rate_id}

Webhook endpoints

Endpoint registration, signing secrets and delivery attempts.

Operation	Endpoint
List webhook endpoints	GET /v1/webhook_endpoints
Create a webhook endpoint	POST /v1/webhook_endpoints
Delete webhook endpoint	DELETE /v1/webhook_endpoints/{endpoint_id}
Get webhook endpoint	GET /v1/webhook_endpoints/{endpoint_id}
Update webhook endpoint	POST /v1/webhook_endpoints/{endpoint_id}
List webhook endpoint deliveries	GET /v1/webhook_endpoints/{endpoint_id}/deliveries
Get webhook delivery	GET /v1/webhook_endpoints/{endpoint_id}/deliveries/{delivery_id}
Redeliver webhook delivery	POST /v1/webhook_endpoints/{endpoint_id}/deliveries/{delivery_id}/redeliver
Rotate webhook endpoint secret	POST /v1/webhook_endpoints/{endpoint_id}/rotate_secret
List event types	GET /v1/webhook_endpoints/event_types

Events

The immutable log every webhook is delivered from.

Operation	Endpoint
List events	GET /v1/events
Get event	GET /v1/events/{event_id}
Stream events	GET /v1/events/stream

Metrics

Aggregate revenue and subscription counts for a dashboard.

Operation	Endpoint
Get home metrics	GET /v1/metrics/home

API keys

Mint, scope and revoke the keys that reach this API.

Operation	Endpoint
List API keys	GET /v1/api_keys
Create API key	POST /v1/api_keys
Get API key	GET /v1/api_keys/{api_key_id}
Revoke API key	POST /v1/api_keys/{api_key_id}/revoke

Audit logs

Who changed what, from the console or the API.

Operation	Endpoint
List audit logs	GET /v1/audit_logs
Get audit log	GET /v1/audit_logs/{audit_log_id}

Tenant

Your account settings, branding and data export.

Operation	Endpoint
Get billing profile	GET /v1/tenant/billing_profile
Update billing profile	POST /v1/tenant/billing_profile
Get tenant capabilities	GET /v1/tenant/capabilities
Export tenant data	GET /v1/tenant/export
Get portal branding	GET /v1/tenant/portal_branding
Update portal branding	POST /v1/tenant/portal_branding
Rotate tenant provider credential	POST /v1/tenant/provider_credential

Test clocks

Advance time in test mode to exercise a year of billing in a minute.

Operation	Endpoint
List test clocks	GET /v1/test_clocks
Create test clock	POST /v1/test_clocks
Delete test clock	DELETE /v1/test_clocks/{test_clock_id}
Get test clock	GET /v1/test_clocks/{test_clock_id}
Advance test clock	POST /v1/test_clocks/{test_clock_id}/advance

Billing portal

Server-side entry points for the customer-facing portal.

Operation	Endpoint
Create portal session	POST /v1/billing_portal/sessions
Revoke portal session	POST /v1/billing_portal/sessions/{session_id}/revoke