Customers

Provision and manage end customers under your partner account. A single atomic call creates the customer account, organization, plan, add-ons, and (optionally) sends the welcome email.

POST/v1/customers

Create a customer with a plan, optional add-ons, and account focus mode. Deducts wholesale cost from your credits.

Request body

Name	Type	Description
`email`required	string	Customer email. Must be unique within your partner account.
`name`	string	Customer full name.
`companyName`	string	Customer company / organization name.
`phone`	string	Customer phone number.
`planId`required	string	BigMind plan ID you have enabled in your retail pricing.
`seats`	integer (1–1000)	Number of user seats. Defaults to 1.
`addOns`	object	Extra storage / servers / databases (see below).
`sendWelcomeEmail`	boolean	Send branded welcome email to the customer. Defaults to true.
`language`	string (max 10)	ISO language code for emails and UI (e.g. "en", "es").
`trial`	boolean	Start the customer on the free trial: free for you, 15 days, a small whole-account storage allowance (Business 10 GB hot + 1 GB cold, Home 5 GB). It converts to the plan when it ends and the plan is charged then. Not available on DR plans; one per email address.
`trialDays`	integer (0–90)	Deprecated. Any value above 0 also starts the free trial; its length is always the standard one.

Add-on units

Name	Type	Description
`hotStorageGB`	integer	Extra hot storage in GB (canonical). e.g. 2000 = 2 TB.
`hotStorageUnits`	integer	Legacy: extra hot storage in 1 TB units (folded to GB). Prefer hotStorageGB.
`coldStorageUnits`	integer	Extra cold storage. Each unit = 1 TB.
`deepFreezeUnits`	integer	Extra deep-freeze storage. Each unit = 1 TB.
`extraServers`	integer	Extra server seats beyond plan.
`mysqlDatabases`	integer	MySQL backup databases.
`mssqlDatabases`	integer	MSSQL backup databases.
`extraWorkspaces`	integer	Extra workspaces.

Example

curl -X POST https://app.bigmind.com/api/partner/v1/customers \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "email": "acme@example.com",
    "name": "Acme Co",
    "planId": "bigmind-standard-yearly",
    "seats": 5,
    "addOns": { "coldStorageUnits": 2, "extraServers": 3 },
    "sendWelcomeEmail": true
  }'

Common error codes: VALIDATION_FAILED, CUSTOMER_EXISTS (409), INVALID_PLAN, PLAN_NOT_ENABLED, INSUFFICIENT_CREDITS (returns required + current + cost breakdown), TRIAL_EXPIRED, TRIAL_NOT_AVAILABLE, TRIAL_ALREADY_USED (409), TRIAL_LIMIT_REACHED (409), FREE_ACCOUNTS_DISCONTINUED.

GET/v1/customers

List your customers, paginated and filterable.

Name	Type	Description
`page`	integer	Page number (1-indexed). Defaults to 1.
`limit`	integer (1–200)	Items per page. Defaults to 20.
`status`	string	Filter by status: "active", "suspended", "deleted".
`planId`	string	Filter by plan ID.
`search`	string	Partial match on email, name, or companyName.

Monitoring fields on every row

Each customer row also carries these fields, so one paginated pass syncs your whole account base without a per-customer /usage or /devices call:

Field	Type	Description
`usedStorageGB`	number	Storage counted against the customer's hot quota, in SI GB (2 dp): hot-tier files plus DR images and database backups; cold and deep-freeze tiers are not included. The same figure as GET /v1/customers/{id}/usage → storage.usedGB.
`lastBackupAt`	ISO 8601 \| null	Most recent backup across the customer's devices, excluding deleted devices (GET /v1/customers/{id}/devices still lists deleted devices, so its newest lastBackup can be later). null if nothing has backed up yet.
`subscriptionExpiresAt`	ISO 8601 \| null	End of the current period: for a trial customer the trial end, otherwise the date the next renewal is charged to your credits. null for plans that never renew. Meaningful for active and trial customers; a suspended or cancelled customer keeps its last value. Also returned by GET /v1/customers/{id}.
`lastLoginAt`	ISO 8601 \| null	Last sign-in by the customer's owner account. null if nobody has signed in yet.

The summary object

summary describes every customer the filters (status, planId, search) match, not only the returned page. It is cached for up to 60 seconds; changes made through the API or the portal refresh it at once.

Field	Type	Description
`totalCustomers`	integer	Customers the filters match.
`activeCustomers, billingActiveCustomers, expiredCustomers`	integer	activeCustomers: status active and the service has not expired. billingActiveCustomers: status active, expired services included. expiredCustomers: the difference.
`inactiveCustomers`	integer	Customers with status inactive or cancelled.
`totalRevenue, averageRevenuePerCustomer, activeCustomersWithoutRetailPrice`	number \| null	Monthly retail revenue of the active customers (a yearly price counts one twelfth). Customers with no retail price are counted in activeCustomersWithoutRetailPrice and left out of the total and the average. null when revenueUnavailable is set.
`recentCreditUsageTotal, averageRecentCreditUsage`	number	Credits used in the last 30 days by these customers: the total, and the total divided by totalCustomers.
`revenueUnavailable`	object \| null	null, or why revenue was not computed: REVENUE_SCAN_CAP_EXCEEDED when more than 10,000 customers have status active.

curl -H "Authorization: Bearer sk_live_..." \
  "https://app.bigmind.com/api/partner/v1/customers?status=active&limit=50"

GET/v1/customers/{id}

Get a single customer with full billing config, credit history, and recent support tickets.

curl -H "Authorization: Bearer sk_live_..." \
  https://app.bigmind.com/api/partner/v1/customers/pc_42_1715600000000

Returns CUSTOMER_NOT_FOUND (404) if the customer doesn't belong to your partner account.

PATCH/v1/customers/{id}

Change plan, seats, or add-ons. Charges or refunds prorated credit based on remaining days in the current billing period.

Name	Type	Description
`name`	string	Update customer display name.
`companyName`	string
`phone`	string
`planId`	string	Switch to a different enabled plan. Prorated.
`seats`	integer	Change seat count. Prorated. Storage quotas scale proportionally.
`addOns`	object	Replace the add-on quantities. Prorated.
`language`	string	Update customer language.
`calculateProrating`	boolean	Set false to skip prorated credit adjustment (rare). Defaults to true.

Add-on input fields

Update uses a slightly different add-on shape than create: hotStorage500GBUnits (500 GB blocks) and hotStorageUnits (1 TB blocks) are separate fields.

curl -X PATCH https://app.bigmind.com/api/partner/v1/customers/pc_42_... \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "seats": 10, "addOns": { "coldStorageUnits": 5 } }'

Returns INSUFFICIENT_CREDITS (400) if the partner balance is below the prorated charge.

POST/v1/customers/{id}/suspend

Reversibly suspend a customer. They keep sign-in and read access to their data; backups, restores and downloads are refused until reactivated. No data is deleted, no refund issued.

curl -X POST https://app.bigmind.com/api/partner/v1/customers/pc_42_.../suspend \
  -H "Authorization: Bearer sk_live_..."

Idempotent — re-suspending a suspended customer is a no-op.

POST/v1/customers/{id}/reactivate

Reverse a suspension. Cannot reactivate deleted customers.

curl -X POST https://app.bigmind.com/api/partner/v1/customers/pc_42_.../reactivate \
  -H "Authorization: Bearer sk_live_..."

DELETE/v1/customers/{id}

Soft-delete the customer. Suspends their organization, revokes access tokens, cancels the subscription, and refunds the prorated unused wholesale cost back to your partner credits.

curl -X DELETE https://app.bigmind.com/api/partner/v1/customers/pc_42_... \
  -H "Authorization: Bearer sk_live_..."

POST/v1/customers/{id}/send-welcome

Resend the branded welcome email to the customer.

curl -X POST https://app.bigmind.com/api/partner/v1/customers/pc_42_.../send-welcome \
  -H "Authorization: Bearer sk_live_..."

GET/v1/customers/{id}/usage

Storage used / quotas / device + file counts for a single customer.

{
  "success": true,
  "data": {
    "customerId": "pc_42_...",
    "storage": {
      "usedGB": 214.5,
      "hotQuotaGB": 2500,
      "coldQuotaGB": 2000,
      "deepFreezeQuotaGB": 0
    },
    "deviceCount": 8,
    "fileCount": 124803
  }
}

GET/v1/customers/{id}/devices

List the customer's backup devices (read-only).

{
  "success": true,
  "data": {
    "devices": [
      {
        "id": "bd_...",
        "name": "DESKTOP-ACME-01",
        "platform": "windows",
        "status": "active",
        "lastBackup": "2026-05-12T18:42:11.000Z",
        "createdAt": "2026-04-02T10:11:30.000Z"
      }
    ]
  }
}