BigMindBigMindBigMind
Partner API
Sign inGet an API key
Partner API
OverviewAuthenticationCustomersPlansQuotesAccount & UsageBackup statusWebhooksError codesChangelog

Account & Usage

Read-only endpoints for chargeback, billing reconciliation, and monitoring your partner account.

GET/v1/account

Your 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
FieldTypeDescription
tier, tierDisplayName, discountPercentstring, string, number | nullThe 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.
priceTemplateobject | nullFor a reseller on its distributor's price template: { id, name }. null for a partner on a tier.
creditsBalancenumberPrepaid 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.
giftCreditobject | nullThe 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.
distributorobject | nullFor 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, isSandboxstring, booleanstatus 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.
GET/v1/account/credits/history

Paginated credit usage log — every charge, refund, and adjustment.

NameTypeDescription
pageinteger ≥ 1Defaults to 1.
limitinteger 1–200Defaults 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.

GET/v1/account/ledger

The 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.

NameTypeDescription
from, toISO 8601The window on the row's time, [from, to). Both optional; from must be before to.
customerIdstringOnly the rows that name this customer (charges and refunds).
kindstringcharge, refund, top_up, top_up_refund, grant, reclaim, expiry or adjustment.
sourcestringwallet (your prepaid credit moved), distributor (charged to your distributor's account for you, or granted / reclaimed by it), bm1 (the archive).
page, limitintegerlimit 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

kindsignDescription
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.

GET/v1/invoices

Your 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"
GET/v1/account/statements

Resellers 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"
GET/v1/customers/{id}/usage

Storage 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
GET/v1/usage/summary

Partner-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"
FieldTypeDescription
credits.creditsUsednumberWhat was spent in the window: every charge (new customers, upgrades, renewals, add-ons). Refunds are not netted into it.
credits.creditsRefundednumberWhat came back in the window: deletions, downgrades and reversed charges, as a positive number.
credits.netCreditsnumbercreditsUsed minus creditsRefunded.
customerCountintegerEvery 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.