QBitFlow
Get started

API reference

Hosted subscriptions

  • 1 endpoint

Every route acts with what the subscription's wallet signs (a transaction or a message), never on a merchant's credential.

Get hosted subscription bills#

GET /hosted/subscriptions/:uuid/bills

Lists a subscription's 10 most recent bills, newest first, in their public shape (public: the id is the secret; one page). An unknown subscription, or another kind of id, answers 404; a subscription not billed yet, no items.

Auth
None needed
On-Behalf-Of
Not used (public route)
Idempotency-Key
Ignored
Success
200
Request

request.sh

curl "https://api.qbitflow.app/v2/hosted/subscriptions/$SUBSCRIPTION_UUID/bills"# 200: a page of Bill ({ items, hasMore: false })

Path parameters

  • uuidstringRequired

    The subscription: sub@… or its bare uuid

    txuuid

Response

A page: { "items": Bill[], "hasMore": …, "nextCursor"?: … }. Pass nextCursor back as cursor for the next page; it is absent when hasMore is false.

30 fields of each Bill

11 fields only its owner reads are never sent here (a public route).

  • uuidstring

    allow read and create, (generated on creation of the payment link)

    A prefixed id (pay@…, sub@…)

  • createdAtstring
  • fromstring
  • tostring
  • amountstring

    The amount in the currency's units, exact, a decimal string ("10" for 10 USDC): amountMinUnits / 10^decimals

  • amountMinUnitsstring

    The amount in the currency's smallest unit, a string of digits ("10000000" for 10 USDC, 6 decimals)

  • amountUsdstring

    What the customer paid, in USD, a decimal string: the price (and, on a one-time payment, the fees its checkout added: fees), which the contracts split between QBitFlow's fee (the referrer's share included), the organization's fee and the merchant (settlement.split). The network fee a customer pays on top (settlement.split.networkFee) is not in it

  • currencyIdinteger

    The currency paid in, written as the currency object under currency (GET /currencies/:id)

  • txHashstring

    Hash of the transaction in the blockchain

  • chainstringOptional

    The chain it was paid on: ETH (Ethereum), BASE (Base) or SOL (Solana), the testnet's for a test-mode transfer (currency.test)

  • explorerUrlstringOptional

    Its transaction on the chain's block explorer (the testnet's in test mode). Omitted without a txHash

  • testboolean

    Whether this is test data (testnets) or live data

  • productNamestring

    What was paid for: the subscription's product name when the bill was paid (the first bill: as it was when the checkout was created). Later product edits don't change it

  • productDescriptionstring

    Same, for the product's description. Absent without one

  • productUuidstringOptional

    The subscription's product

  • subscriptionUuidstring

    The subscription it bills (sub@…)

  • periodStartstringOptional

    The start of the period the bill paid: its due date (the subscription's start for its first bill). Omitted on bills recorded before it was

  • periodEndstringOptional

    The end of the period the bill paid: the subscription's next bill. Paid until then. Omitted on bills recorded before it was

  • confirmedAtstringOptional

    When the chain confirmed it: its block's time (settlement.transaction.blockTime). Absent only on records made before it was recorded

Errors

The common codes only, as any route (what each means):

Edge cases

The contract's rules for these routes: Authentication & roles · Ids · Bills (public).

Read all 3

Authentication & roles

  • GET /:uuid/bills is public (no credential): the management page's bill history; the subscription's id is the secret.
  • The others are dashboard-only (API keys → 404): the checkout's intent and send (POST /intent, POST "") and the management page's actions, each an intent (…/intent, 201) then its send (200): /:uuid/cancel, /:uuid/increase-allowance, /:uuid/update-max-amount, /:uuid/pause, /:uuid/resume; and POST /:uuid/upgrade-trial (201).

Ids

  • :uuid is the subscription's id: sub@… or its bare uuid (the same subscription, the same intents: an intent asked with one form is sent with the other). Another kind of id (pay@…) → 404; a malformed one → 400 validation_failed on uuid. The subscription moved from the bodies to the path: the bodies are { numPeriods } (allowance intent), { signedTransaction } (the sends), { signature } (pause, resume) or none.
  • An unknown or cancelled subscription → 404 on every action (its bills stay readable).

Bills (public)

  • GET /:uuid/bills answers the subscription's 10 most recent bills, newest first, in one page ({"items": [...], "hasMore": false}; every bill, page by page, is the merchant's GET /subscriptions/:uuid/bills). A subscription not billed yet (a trial) → no items. An unknown subscription, or another kind of id (refund@…) → 404. A cancelled subscription's bills stay readable.
  • Each bill is a Bill (Subscriptions and bills § Bills) in its public shape: its currency object, amounts and productName, never its whenAuth fields (userUuid, customerUuid, customer, settlement), even with the merchant's credential.

The codes named here

  • 400validation_failed

    path/query/body failed binding or validation, or a business rule about one input (a field named in errors)