Account & Usage
Read-only endpoints for chargeback, billing reconciliation, and monitoring your partner account.
/v1/accountYour partner profile, the wholesale tier your prices come from, your credit balance, your welcome gift and (for a reseller) your distributor.
curl -H "Authorization: Bearer sk_live_..." https://eu-bigmind2.genie9.com/api/partner/v1/account| Field | Type | Description |
|---|---|---|
tier, tierDisplayName, discountPercent | string, string, number | null | The wholesale tier in force (explorer, starter, growth, scale, enterprise) and its discount off list — the prices GET /v1/plans shows come from it. A reseller priced by its distributor's price template gets tier template, tierDisplayName = the template's name and discountPercent null: a template prices each item, there is no single discount. |
priceTemplate | object | null | For a reseller on its distributor's price template: { id, name }. null for a partner on a tier. |
creditsBalance | number | Prepaid credit, in USD (1 credit = US$1). Sales, upgrades and renewals are charged to it; a distributor-funded partner keeps 0 here and is charged on the distributor's account. |
giftCredit | object | null | The welcome gift while it is open: { active, endsAt }. It is kept by the first top-up and taken back if the 30 days end without one. null once settled. |
distributor | object | null | For a reseller: { id, name, controlsPricing }. When controlsPricing is true your retail prices are set on the distributor's template; PLAN_NOT_ENABLED with action contact_distributor means the plan is not on it yet. |
status, isSandbox | string, boolean | status is active, trial or expired (expired = read-only: every write answers PARTNER_READ_ONLY). isSandbox marks a distributor test account whose sales never reach a real ledger. |
/v1/account/credits/historyPaginated credit usage log — every charge, refund, and adjustment.
| Name | Type | Description |
|---|---|---|
page | integer ≥ 1 | Defaults to 1. |
limit | integer 1–200 | Defaults to 50. Anything outside the range is a 400 VALIDATION_FAILED. |
curl -H "Authorization: Bearer sk_live_..." \
"https://eu-bigmind2.genie9.com/api/partner/v1/account/credits/history?page=1&limit=50"Negative creditsUsed values represent refunds (e.g., customer deletions, plan downgrades). A distributor-funded partner sees its sales here too (usage types ending in _distributor): they were charged to the distributor, not to creditsBalance.
/v1/account/ledgerThe signed credit ledger: every movement of your credit from every source in one row shape — charges and refunds, top-ups, your distributor's grants and reclaims, expiries, adjustments, and your archived BigMIND 1.0 ledger. For reconciliation and exports; credits/history stays as the v1.0 contract.
| Name | Type | Description |
|---|---|---|
from, to | ISO 8601 | The window on the row's time, [from, to). Both optional; from must be before to. |
customerId | string | Only the rows that name this customer (charges and refunds). |
kind | string | charge, refund, top_up, top_up_refund, grant, reclaim, expiry or adjustment. |
source | string | wallet (your prepaid credit moved), distributor (charged to your distributor's account for you, or granted / reclaimed by it), bm1 (the archive). |
page, limit | integer | limit 1–200 (default 50). Or send after=nextCursor from the previous page to walk the whole ledger for an export; page is ignored then. |
curl -H "Authorization: Bearer sk_live_..." \
"https://eu-bigmind2.genie9.com/api/partner/v1/account/ledger?from=2026-10-01T00:00:00Z&to=2026-11-01T00:00:00Z&source=wallet&limit=200"Row kinds
| kind | sign | Description |
|---|---|---|
charge | − | A sale, renewal, upgrade or usage (expedited restore, AI consultation …) charged to you. usageType says which. |
refund | + | Money back: a deleted customer's unused period, a licence cancellation, a failed expedite. |
top_up | + | A credit purchase that settled (pending or failed checkouts are not rows). BM1 top-ups too. |
top_up_refund | − | A credit purchase refunded to your card: the credit leaves the wallet. |
grant / reclaim | + / − | Credit your distributor put in your wallet, or took back (source distributor). |
expiry | − | Credit that expired (12 months) or a welcome gift clawed back. |
adjustment | ± | A manual or administrative change (an agreed credit, a correction, test credit on a sandbox). |
Reconciliation: the movement of your prepaid balance in a window is the sum of amount over the rows with source=wallet plus the grant and reclaim rows (your distributor putting credit in your wallet or taking it back carries source=distributor). Charges with source=distributor did not move your wallet: an open-credit reseller's sales are charged to the distributor. The rows that come from your usage history (every usageType other than credit_purchase, the distributor memo types and the archive) match usage/summary for the same window: their negative amounts add up to creditsUsed, their positive amounts to creditsRefunded — except the 0-credit marker rows (expiry_warning, gift_reminder), which the ledger leaves out and usage/summary counts in usageEvents. With a kind or source filter, total is exact only when the whole window was scanned (else null); walk with the cursor for an export.
/v1/invoicesYour invoices, newest first: ?status= (draft, open, sent, paid, void, uncollectible, refunded), ?type= (credits; subscription and overage for legacy rows), ?from= / ?to= on the issue date as [from, to), page / limit (≤ 200). GET /v1/invoices/{id} is one invoice with its line items, billing details and exchange-rate facts; GET /v1/invoices/{id}/pdf is the PDF — a 302 to the Stripe-hosted document when the invoice was issued by Stripe, else rendered and streamed (application/pdf).
curl -H "Authorization: Bearer sk_live_..." "https://eu-bigmind2.genie9.com/api/partner/v1/invoices?status=paid&limit=50"
curl -L -o INV-42-00017.pdf -H "Authorization: Bearer sk_live_..." "https://eu-bigmind2.genie9.com/api/partner/v1/invoices/inv_…/pdf"/v1/account/statementsResellers only (a direct partner gets 404 NOT_A_RESELLER). Without ?month=: your distributor and the twelve months available. With ?month=YYYY-MM: the monthly statement — what your distributor invoices you: credit granted, usage on your credit line, credit reclaimed, totalDue, the credit line left, spend per customer and every line. ?format=csv for the same as a file.
curl -H "Authorization: Bearer sk_live_..." "https://eu-bigmind2.genie9.com/api/partner/v1/account/statements?month=2026-09"
curl -o statement-2026-09.csv -H "Authorization: Bearer sk_live_..." "https://eu-bigmind2.genie9.com/api/partner/v1/account/statements?month=2026-09&format=csv"/v1/customers/{id}/usageStorage used and device/file counts for a single customer.
curl -H "Authorization: Bearer sk_live_..." \
https://eu-bigmind2.genie9.com/api/partner/v1/customers/pc_42_.../usage/v1/usage/summaryPartner-wide rollup. Optional from/to date range filters credit-usage events.
curl -H "Authorization: Bearer sk_live_..." \
"https://eu-bigmind2.genie9.com/api/partner/v1/usage/summary?from=2026-10-01T00:00:00Z&to=2026-10-31T23:59:59Z"| Field | Type | Description |
|---|---|---|
credits.creditsUsed | number | What was spent in the window: every charge (new customers, upgrades, renewals, add-ons). Refunds are not netted into it. |
credits.creditsRefunded | number | What came back in the window: deletions, downgrades and reversed charges, as a positive number. |
credits.netCredits | number | creditsUsed minus creditsRefunded. |
customerCount | integer | Every customer that is not deleted (active, trial, suspended and the rest). |
Date params accept ISO 8601 timestamps. Both are optional — omit to get all-time totals. from after to is a 400 VALIDATION_FAILED.