API reference
JSON over HTTPS, generated from the API's contract. What every route shares, then every group.
The 60 routes an API key can call: what each takes, returns and can refuse, with its cURL request and the SDKs' example.
Anatomy · request
POST: the method, as each endpoint names ithttps://api.qbitflow.app/v2/products: the base URL and the route: the version is part of the pathX-API-Key: sk_…: your key: its space and mode decide everything the request seesOn-Behalf-Of: <member>: optional: an organization's key acting in a member's spaceIdempotency-Key: <uuid>: on creates: a retry with the same key never creates twice
Base URL and versions
Every path is relative to:
https://api.qbitflow.app/v2
The version is part of the path, and the SDKs default to this URL. A trailing slash is ignored
(/products = /products/). Keys, parameters and enum values are lowerCamelCase (userUuid,
pastDue); error codes stay snake_case.
Authentication
Send your key in the X-API-Key header of every authenticated request:
Text
X-API-Key: sk_<test|live>_<uuid>_<secret>- Opaque. Created in the dashboard and shown once; the API can't create or revoke keys.
- One space, one mode. An organization's key acts as an admin of the organization; a member's key acts as that member. It only sees its space's resources.
- Admin routes say "an admin key": a member's key answers
403 forbidden. - A missing, unknown, deleted or expired key answers
401 unauthorized. A few routes are public (the currency lookups, a subscription's public history).
Check which key you hold, and its mode, with GET /me.
On-Behalf-Of
An organization's key acts as one of its members with On-Behalf-Of: <userUuid>
(Member.userUuid, from GET /members). The request then works in the
member's space, in the key's mode, as if the member had sent it.
- The effective role is
user: admin routes answer403. Manage members without the header. - A value that isn't a uuid, or a member's key naming anyone but itself:
403 forbidden. - Not a member of your organization in this mode (another organization's user, an owner or admin,
a removed member):
404 not_found. Existence is never revealed. - Each endpoint says whether it honors the header.
client-on-behalf-of.sh
# An organization key acting in a member's space: the request reads the member's products, in the# key's mode. Without the header, the same key reads the organization's own.curl https://api.qbitflow.app/v2/products \ -H "X-API-Key: $QBITFLOW_API_KEY" \ -H "On-Behalf-Of: $MEMBER_UUID"# 200: a page of Product ({ items, hasMore, nextCursor? })// An organization key acting in a member's space: every request of seller sends// On-Behalf-Of. It shares client's configuration.const seller = client.onBehalfOf(memberUuid);const products = await seller.products.list();console. log( `${products. items. length} products on the first page of the seller's space`);# Every request of this client sends On-Behalf-Of: it acts in the member's space.seller = client.on_behalf_of(member_uuid) # shares the connections and settings of clientproducts = seller.products.list()print(len(products.items), "products on the first page of the seller's space")marketplace/main.go
// A client acting in the member's space (organization key): every request sends// On-Behalf-Of. It shares the connections and configuration of client.seller := client.OnBehalfOf(memberUUID)products, err := seller.Products.List(ctx, nil)if err != nil { log.Fatal(err)}fmt.Println(len(products.Items), "products on the first page of the seller's space")// An organization key acts in a member's space: every request sends On-Behalf-Of.$seller = $client->onBehalfOf( $memberUuid); // shares $client's transport and configurationecho count( $seller->products->list( )->items), " products on the first page of the member's space\n";Every request
One line each, the details on the linked page.
Idempotency-Key and X-Request-Id
Send one Idempotency-Key per create, the same on every retry: it never runs twice
(idempotency). Every response carries X-Request-Id (yours, if you sent
a plain token of 1 to 128 letters, digits and -_.:, else a new UUID), repeated as requestId in
every error: log it, quote it to support.
Pagination
Lists take a cursor: pass nextCursor back as cursor until hasMore is false; limit is
clamped, never refused (pagination).
Errors
One body for every failure: branch on code and the status, never on error
(every code).
Rate limits
Past a limit, 429 rate_limit_exceeded with Retry-After: the request did nothing, wait and send
it again (rate limits).
Test mode
The key picks the mode: a test key only sees test resources, on test networks, and nothing carries over to live (test mode, going live).
Resource groups
One page per group. Also: webhook events and every error code.
Products5 endpoints
Customers5 endpoints
Currencies2 endpoints
Checkout sessions4 endpoints
Payments and transactions4 endpoints
Subscriptions and bills7 endpoints
Hosted subscriptions1 endpoint
Refunds2 endpoints
Me1 endpoint
Account and credential1 endpoint
Members and held funds5 endpoints
Held funds3 endpoints
Wallets3 endpoints
Invitations3 endpoints
API keys1 endpoint
Accounting1 endpoint
Webhooks12 endpoints
- GET /webhooks/
event-types - GET /webhooks/
endpoints - POST /webhooks/
endpoints - GET /webhooks/
endpoints/ :uuid - PATCH /webhooks/
endpoints/ :uuid - DELETE /webhooks/
endpoints/ :uuid - POST /webhooks/
endpoints/ :uuid/ test - GET /webhooks/
endpoints/ :uuid/ deliveries - GET /webhooks/
events - GET /webhooks/
events/ :id - POST /webhooks/
events/ :id/ resend - POST /webhooks/
verify
- GET /webhooks/