# Account (part 1 of 4)

> For AI agents: the full docs index is at https://brixsignage.com/llms.txt, and every page has a markdown twin (add .md to the path).

Account is split into 4 pages: [part 1](https://brixsignage.com/developers/api/account.md) (`/v1/account` to `/v1/account/brix-plan/screens/estimate`), [part 2](https://brixsignage.com/developers/api/account-2.md) (`/v1/account/brix-plan/screens/request` to `/v1/account/location-payment`), [part 3](https://brixsignage.com/developers/api/account-3.md) (`/v1/account/location-payment` to `/v1/account/payment-card/complete`), [part 4](https://brixsignage.com/developers/api/account-4.md) (`/v1/account/payment-card/setup` to `/v1/account/upgrade-annual/estimate`).

Base URL `https://api.brixsignage.com`. Send `Authorization: Bearer $BRIX_API_KEY` unless an operation says Auth: none or Auth: no API key. The Permission line names what the key must hold. See [Authentication and scopes](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md).

- [GET /v1/account](#get-v1-account)
- [POST /v1/account/about-you](#post-v1-account-about-you)
- [GET /v1/account/billing-address](#get-v1-account-billing-address)
- [PUT /v1/account/billing-address](#put-v1-account-billing-address)
- [POST /v1/account/billing-mode](#post-v1-account-billing-mode)
- [POST /v1/account/brix-plan](#post-v1-account-brix-plan)
- [PUT /v1/account/brix-plan/cadence](#put-v1-account-brix-plan-cadence)
- [GET /v1/account/brix-plan/playing](#get-v1-account-brix-plan-playing)
- [PUT /v1/account/brix-plan/playing](#put-v1-account-brix-plan-playing)
- [GET /v1/account/brix-plan/pool](#get-v1-account-brix-plan-pool)
- [GET /v1/account/brix-plan/quote](#get-v1-account-brix-plan-quote)
- [PUT /v1/account/brix-plan/screens](#put-v1-account-brix-plan-screens)
- [POST /v1/account/brix-plan/screens/estimate](#post-v1-account-brix-plan-screens-estimate)

Every 4xx and 5xx response below returns this body:

| Field | Type | Description |
| --- | --- | --- |
| `error` | string | Machine-readable code: `unauthorized`, `forbidden`, `not_found`, `validation_error`, `conflict`, `rate_limited`, `internal_error`, … |
| `message` | string | Human-readable explanation. Safe to show an operator. |
| `requestId` | string | Present on 5xx: quote it to support. |

## GET /v1/account

Get account overview

Returns the workspace plan, subscription status, screen pool size, trial or paid status, and onboarding progress.

**Notes.**
- `email`, `emailVerifiedAt` and `verificationEmailLastSentAt` describe the CALLING user; they are null for an API key.
- On a workspace created before the onboarding step existed, a null `prefs.onboardingCompletedAt` is filled with the workspace's creation time (and saved).

Auth: Bearer token. Permission: `billing.view`.

```bash
curl "https://api.brixsignage.com/v1/account" \
  -H "Authorization: Bearer $BRIX_API_KEY"
```

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | Account |  |
| `data.scheduledScreenPool` | object \| null | A screen plan reduction queued for the renewal. |
| `data.trialPlan` | object \| null | During a free trial billed by us: the plan that starts when the trial ends, charged to the saved card then. Null when none is set. |
| `data.contract` | BillingTerm \| null |  |
| `data.id` | string | Workspace id (the account id support asks for). |
| `data.partnerManaged` | boolean | A partner (white-label or reseller) manages this workspace. Its screens never show a corner mark, so the console hides the "Logo on screens" switch. |
| `data.whiteLabel` | boolean | A partner bills this workspace; Brix billing does not apply. |
| `data.freeAccess` | boolean | This workspace has free access (an external tester). There is no plan to choose and nothing is billed. |
| `data.status` | "active" \| "cancel_scheduled" \| "paused" \| "past_due" \| "suspended" \| "cancelled" |  |
| `data.pauseUntil` | string \| null |  |
| `data.cancelEffectiveAt` | string \| null |  |
| `data.cancelReason` | "provider" \| "trial_expired" \| "voluntary" \| "nonpayment" \| null |  |
| `data.everPaid` | boolean |  |
| `data.deletionRequestedAt` | string \| null |  |
| `data.billingBanner` | BillingBanner \| null |  |
| `data.survey` | any | The last cancellation survey (`{ reason, competitor, returnLikelihood, comment }`), or null. |
| `data.prefs` | WorkspacePrefs | Workspace preferences. Every key is present (defaults filled in). |
| `data.prefs.timeFormat` | "12h" \| "24h" |  |
| `data.prefs.weekStart` | "mon" \| "sun" |  |
| `data.prefs.dateFormat` | "mdy" \| "dmy" \| "ymd" |  |
| `data.prefs.tempUnits` | "f" \| "c" |  |
| `data.prefs.timeZone` | string | IANA time zone. Screens without their own zone use it, and so do schedules timed by the workspace. |
| `data.prefs.language` | string | BCP 47 language tag. |
| `data.prefs.multinational` | boolean | Shows the per-location and per-screen language settings. |
| `data.prefs.newLocationsPayFirst` | boolean | New locations pay for themselves before going live: each adds its own card, and its screens show a hold card (not billed to the account) until then. Default false. Turning it on needs Brix billing with a running plan (409 otherwise). |
| `data.prefs.navExtras` | array of string | Console pages switched on that the workspace size hides by default. |
| `data.prefs.appBranding` | object | The look of the on-screen apps. |
| `data.prefs.appBranding.accent` | string |  |
| `data.prefs.appBranding.accent2` | string |  |
| `data.prefs.appBranding.theme` | "dark" \| "light" |  |
| `data.prefs.appBranding.backdrop` | "brand" \| "wash" \| "plain" \| "aurora" \| "dots" \| "grid" \| "solid" |  |
| `data.prefs.appBranding.intensity` | number |  |
| `data.prefs.brandKits` | array of object | Saved looks. An app follows one with `config.brandKitId`. A write replaces the whole list (at most 50). |
| `data.prefs.brandKits[].id` | string |  |
| `data.prefs.brandKits[].name` | string |  |
| `data.prefs.brandKits[].accent` | string |  |
| `data.prefs.brandKits[].accent2` | string |  |
| `data.prefs.brandKits[].theme` | "dark" \| "light" |  |
| `data.prefs.brandKits[].backdrop` | "brand" \| "wash" \| "plain" \| "aurora" \| "dots" \| "grid" \| "solid" |  |
| `data.prefs.brandKits[].intensity` | number |  |
| `data.prefs.audio` | object | Default screen volume and a master mute. |
| `data.prefs.audio.volume` | number | 0–100. |
| `data.prefs.audio.muted` | boolean |  |
| `data.prefs.brand` | object |  |
| `data.prefs.brand.companyName` | string |  |
| `data.prefs.brand.logoUrl` | string |  |
| `data.prefs.requireAltText` | boolean |  |
| `data.prefs.showScreenLogo` | boolean |  |
| `data.prefs.keepTvOnInput` | boolean | Default for "Keep the TV on this input" on screens that have not set their own. |
| `data.prefs.standbyContentKind` | string \| null | What a screen with nothing to play shows; null = the default card. |
| `data.prefs.standbyContentId` | string \| null |  |
| `data.prefs.tier` | "simple" \| "team" \| "enterprise" | Workspace size. It sets console defaults, not access. |
| `data.prefs.industry` | string \| null |  |
| `data.prefs.onboardingCompletedAt` | string \| null |  |
| `data.prefs.setupStep` | string \| null | Walkthrough position (`s1`…`s5`, `l1`…`l6`, `done`). |
| `data.prefs.welcomeDeclinedAt` | string \| null | When the owner declined the setup questions. Null if never declined, or answered later. |
| `data.prefs.aboutYouDue` | boolean | The workspace is asked the first-sign-in questions (workspaces created from 2026-10-14). |
| `data.prefs.aboutYouAt` | string \| null | When the first-sign-in questions were answered. |
| `data.prefs.expectedScreens` | integer \| null | How many screens the owner said they expect. |
| `data.prefs.orgNameSet` | boolean |  |
| `data.prefs.tiers` | array of integer | Location tree levels in use. |
| `data.prefs.tierLabels` | object | Custom names for the location tree levels. |
| `data.prefs.requireTwoFactor` | boolean |  |
| `data.prefs.requireSso` | boolean |  |
| `data.prefs.requireSsoPending` | boolean | Single sign-on was required, and turns on after the first sign-in through the connection. |
| `data.prefs.requireSsoPendingSince` | string \| null |  |
| `data.prefs.ai` | object |  |
| `data.prefs.ai.enabled` | boolean |  |
| `data.prefs.ai.features` | object | Per feature (`tags`, `alt-text`, `moderation`, `transcription`, `translation`, `focal-region`, `embedding`); an absent feature follows `enabled`. |
| `data.prefs.ai.dailyCallLimit` | integer \| null |  |
| `data.prefs.ai.redactPersonalData` | boolean |  |
| `data.prefs.retention` | object | Days kept per stream, only for the streams the workspace has set. An absent stream uses the platform window. |
| `data.prefs.retention.offline` | number |  |
| `data.prefs.retention.screenshots` | number |  |
| `data.prefs.retention.playback` | number |  |
| `data.prefs.retention.deviceLogs` | number |  |
| `data.prefs.retention.vitals` | number |  |
| `data.prefs.retention.replays` | number |  |
| `data.prefs.retention.aiEvents` | number |  |
| `data.prefs.warehouse` | object | Data warehouse feed. Set by Brix; not writable here. |
| `data.prefs.warehouse.enabled` | boolean |  |
| `data.prefs.warehouse.bucketBinding` | string | Set by Brix when the data warehouse feed is provisioned. |
| `data.prefs.warehouse.tables` | array of string |  |
| `data.prefs.warehouse.lookbackDays` | integer |  |
| `data.prefs.supportAccess` | SupportAccessPolicy |  |
| `data.prefs.supportAccess.mode` | "open" \| "notify" \| "approve" | `open`: Brix support may open the workspace. `notify`: it may, and the owners are emailed. `approve`: a person here must approve each request. |
| `data.prefs.supportAccess.grantMinutes` | integer | How long an approval lasts. |
| `data.prefs.supportAccess.requestTtlMinutes` | integer | How long a request waits for an answer before it expires. |
| `data.prefs.kioskHasGlobalPin` | boolean | A workspace Screen Lock PIN is set. The PIN and its hash are never returned. |
| `data.region` | "us" \| "eu" \| "oc" \| "apac" | Where the workspace's data is stored. |
| `data.dbRegion` | "us" \| "eu" \| "oc" \| "apac" | Where the workspace's records are stored. Can differ from `region` for workspaces created before regional sign-up: media in the region, records on the primary. |
| `data.billingProvider` | "chargebee" \| "brix" | `brix`: Brix invoices the account (see `payment`). `chargebee`: a card subscription. |
| `data.payment` | AccountPayment \| null | Only when `billingProvider` is `brix`. |
| `data.subscriptionStatus` | string \| null |  |
| `data.cadence` | "monthly" \| "annual" \| null |  |
| `data.billableScreens` | integer | Screens that count toward the bill now. |
| `data.licensedScreens` | integer \| null | Screens bought (the plan quantity or the term's screens). |
| `data.trialEndsAt` | string \| null |  |
| `data.nextBillingAt` | string \| null |  |
| `data.currentTermEndsAt` | string \| null |  |
| `data.emailVerifiedAt` | string \| null | The calling user's; null for an API key. |
| `data.verificationEmailLastSentAt` | string \| null |  |
| `data.email` | string \| null | The calling user's email; null for an API key. |

Response 401: Missing, expired or revoked bearer token.

Response 403: You do not hold the permission for the whole workspace (a grant at one location is not enough).

Response 5XX: Server error. The body carries a `requestId` to quote to support.

## POST /v1/account/about-you

Answer the first-sign-in questions

Records the answers a new workspace gives at its first sign-in: `screenCount`, the number of screens you expect (a whole number from 1 to 1,000,000, required), `heardFrom`, how you heard about Brix (required, except for a customer of a partner), and `phone`. A phone number is required only for a Google or Microsoft sign-up in the United States or Canada. Returns 422 with the field that is missing or not valid.

Auth: Bearer token. Permission: `billing.edit`.

Request body: `application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `screenCount` | integer | yes | How many screens the workspace expects. Sets `prefs.expectedScreens` and the tier. |
| `heardFrom` | string | no | How they heard about Brix. Required unless the workspace belongs to a partner. |
| `aiPrompt` | string | no | The question they asked an AI assistant, when `heardFrom` names one. |
| `phone` | string | no | Required for a workspace in the US or Canada when the person has no phone on file (`phoneRequired` on GET /v1/account/onboarding); optional elsewhere and in a partner's customer workspace. US and Canada numbers get the North-American checks. |

```bash
curl -X POST "https://api.brixsignage.com/v1/account/about-you" \
  -H "Authorization: Bearer $BRIX_API_KEY" \
  -H "Content-Type: application/json"
```

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | object |  |
| `data.prefs` | WorkspacePrefs | Workspace preferences. Every key is present (defaults filled in). |
| `data.prefs.timeFormat` | "12h" \| "24h" |  |
| `data.prefs.weekStart` | "mon" \| "sun" |  |
| `data.prefs.dateFormat` | "mdy" \| "dmy" \| "ymd" |  |
| `data.prefs.tempUnits` | "f" \| "c" |  |
| `data.prefs.timeZone` | string | IANA time zone. Screens without their own zone use it, and so do schedules timed by the workspace. |
| `data.prefs.language` | string | BCP 47 language tag. |
| `data.prefs.multinational` | boolean | Shows the per-location and per-screen language settings. |
| `data.prefs.newLocationsPayFirst` | boolean | New locations pay for themselves before going live: each adds its own card, and its screens show a hold card (not billed to the account) until then. Default false. Turning it on needs Brix billing with a running plan (409 otherwise). |
| `data.prefs.navExtras` | array of string | Console pages switched on that the workspace size hides by default. |
| `data.prefs.appBranding` | object | The look of the on-screen apps. |
| `data.prefs.appBranding.accent` | string |  |
| `data.prefs.appBranding.accent2` | string |  |
| `data.prefs.appBranding.theme` | "dark" \| "light" |  |
| `data.prefs.appBranding.backdrop` | "brand" \| "wash" \| "plain" \| "aurora" \| "dots" \| "grid" \| "solid" |  |
| `data.prefs.appBranding.intensity` | number |  |
| `data.prefs.brandKits` | array of object | Saved looks. An app follows one with `config.brandKitId`. A write replaces the whole list (at most 50). |
| `data.prefs.brandKits[].id` | string |  |
| `data.prefs.brandKits[].name` | string |  |
| `data.prefs.brandKits[].accent` | string |  |
| `data.prefs.brandKits[].accent2` | string |  |
| `data.prefs.brandKits[].theme` | "dark" \| "light" |  |
| `data.prefs.brandKits[].backdrop` | "brand" \| "wash" \| "plain" \| "aurora" \| "dots" \| "grid" \| "solid" |  |
| `data.prefs.brandKits[].intensity` | number |  |
| `data.prefs.audio` | object | Default screen volume and a master mute. |
| `data.prefs.audio.volume` | number | 0–100. |
| `data.prefs.audio.muted` | boolean |  |
| `data.prefs.brand` | object |  |
| `data.prefs.brand.companyName` | string |  |
| `data.prefs.brand.logoUrl` | string |  |
| `data.prefs.requireAltText` | boolean |  |
| `data.prefs.showScreenLogo` | boolean |  |
| `data.prefs.keepTvOnInput` | boolean | Default for "Keep the TV on this input" on screens that have not set their own. |
| `data.prefs.standbyContentKind` | string \| null | What a screen with nothing to play shows; null = the default card. |
| `data.prefs.standbyContentId` | string \| null |  |
| `data.prefs.tier` | "simple" \| "team" \| "enterprise" | Workspace size. It sets console defaults, not access. |
| `data.prefs.industry` | string \| null |  |
| `data.prefs.onboardingCompletedAt` | string \| null |  |
| `data.prefs.setupStep` | string \| null | Walkthrough position (`s1`…`s5`, `l1`…`l6`, `done`). |
| `data.prefs.welcomeDeclinedAt` | string \| null | When the owner declined the setup questions. Null if never declined, or answered later. |
| `data.prefs.aboutYouDue` | boolean | The workspace is asked the first-sign-in questions (workspaces created from 2026-10-14). |
| `data.prefs.aboutYouAt` | string \| null | When the first-sign-in questions were answered. |
| `data.prefs.expectedScreens` | integer \| null | How many screens the owner said they expect. |
| `data.prefs.orgNameSet` | boolean |  |
| `data.prefs.tiers` | array of integer | Location tree levels in use. |
| `data.prefs.tierLabels` | object | Custom names for the location tree levels. |
| `data.prefs.requireTwoFactor` | boolean |  |
| `data.prefs.requireSso` | boolean |  |
| `data.prefs.requireSsoPending` | boolean | Single sign-on was required, and turns on after the first sign-in through the connection. |
| `data.prefs.requireSsoPendingSince` | string \| null |  |
| `data.prefs.ai` | object |  |
| `data.prefs.ai.enabled` | boolean |  |
| `data.prefs.ai.features` | object | Per feature (`tags`, `alt-text`, `moderation`, `transcription`, `translation`, `focal-region`, `embedding`); an absent feature follows `enabled`. |
| `data.prefs.ai.dailyCallLimit` | integer \| null |  |
| `data.prefs.ai.redactPersonalData` | boolean |  |
| `data.prefs.retention` | object | Days kept per stream, only for the streams the workspace has set. An absent stream uses the platform window. |
| `data.prefs.retention.offline` | number |  |
| `data.prefs.retention.screenshots` | number |  |
| `data.prefs.retention.playback` | number |  |
| `data.prefs.retention.deviceLogs` | number |  |
| `data.prefs.retention.vitals` | number |  |
| `data.prefs.retention.replays` | number |  |
| `data.prefs.retention.aiEvents` | number |  |
| `data.prefs.warehouse` | object | Data warehouse feed. Set by Brix; not writable here. |
| `data.prefs.warehouse.enabled` | boolean |  |
| `data.prefs.warehouse.bucketBinding` | string | Set by Brix when the data warehouse feed is provisioned. |
| `data.prefs.warehouse.tables` | array of string |  |
| `data.prefs.warehouse.lookbackDays` | integer |  |
| `data.prefs.supportAccess` | SupportAccessPolicy |  |
| `data.prefs.supportAccess.mode` | "open" \| "notify" \| "approve" | `open`: Brix support may open the workspace. `notify`: it may, and the owners are emailed. `approve`: a person here must approve each request. |
| `data.prefs.supportAccess.grantMinutes` | integer | How long an approval lasts. |
| `data.prefs.supportAccess.requestTtlMinutes` | integer | How long a request waits for an answer before it expires. |
| `data.prefs.kioskHasGlobalPin` | boolean | A workspace Screen Lock PIN is set. The PIN and its hash are never returned. |

Response 401: Missing, expired or revoked bearer token.

Response 403: You do not hold the permission for the whole workspace (a grant at one location is not enough).

Response 422: `screen_count_required`, `heard_from_required`, `phone_required` or `phone_invalid`.

Response 5XX: Server error. The body carries a `requestId` to quote to support.

## GET /v1/account/billing-address

Get billing address

Returns the billing address on file with the billing provider: the country used to determine invoice tax, and, for the United States and Canada, the state and postal code. The response includes `configured: false` when no billing address has been set yet.

Auth: Bearer token. Permission: `billing.view`.

```bash
curl "https://api.brixsignage.com/v1/account/billing-address" \
  -H "Authorization: Bearer $BRIX_API_KEY"
```

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | object \| object |  |

Response 401: Missing, expired or revoked bearer token.

Response 403: You do not hold the permission for the whole workspace (a grant at one location is not enough).

Response 5XX: Server error. The body carries a `requestId` to quote to support.

## PUT /v1/account/billing-address

Set billing address

Sets the workspace billing address. `country` is required and validated against the ISO 3166-1 country list. For the United States and Canada, `stateCode` and `zip` are also required. This replaces the entire address on file; you cannot update a single field.

**Notes.**
- Answers 400 (not 422) for an invalid address, unlike most validation errors.

Auth: Bearer token. Permission: `billing.edit`.

Request body: `application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `country` | string | yes | Country code or name. |
| `stateCode` | string | no | Required for US and Canada. Stored in upper case. |
| `zip` | string | no | Required for US and Canada. |
| `city` | string | no |  |
| `line1` | string | no |  |

```bash
curl -X PUT "https://api.brixsignage.com/v1/account/billing-address" \
  -H "Authorization: Bearer $BRIX_API_KEY" \
  -H "Content-Type: application/json"
```

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | object |  |
| `data.configured` | true |  |
| `data.address` | object |  |
| `data.address.country` | string \| null | ISO 3166-1 alpha-2. |
| `data.address.stateCode` | string \| null | State or province, without the country prefix (`CA`, `ON`). |
| `data.address.zip` | string \| null |  |
| `data.address.city` | string \| null |  |
| `data.address.line1` | string \| null |  |
| `data.needsState` | boolean |  |

Response 400: `invalid_country` or `state_required` (400, not 422).

Response 401: Missing, expired or revoked bearer token.

Response 403: You do not hold the permission for the whole workspace (a grant at one location is not enough).

Response 409: `no_customer`: billing is not set up yet.

Response 502: The billing provider did not answer; nothing changed.

Response 5XX: Server error. The body carries a `requestId` to quote to support.

## POST /v1/account/billing-mode

Switch billing mode

Switches the workspace between automatic card charging (`auto`) and invoice billing (`invoice`). Switching to invoice billing requires a signed-in user with a verified work email address, so an API key can only switch to automatic charging.

Auth: Bearer token. Permission: `billing.edit`.

Request body: `application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `mode` | "auto" \| "invoice" | yes |  |

```bash
curl -X POST "https://api.brixsignage.com/v1/account/billing-mode" \
  -H "Authorization: Bearer $BRIX_API_KEY" \
  -H "Content-Type: application/json"
```

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | object |  |
| `data.mode` | "auto" \| "invoice" |  |

Response 401: Missing, expired or revoked bearer token.

Response 403: `user_required`: switching to `invoice` needs a signed-in user with a verified work email, so an API key can switch only to `auto`. Also: You do not hold the permission for the whole workspace (a grant at one location is not enough).

Response 409: `email_unverified`, `work_email_required`, `billing_not_configured`, or `under_contract`.

Response 422: `mode` is not `auto` or `invoice`.

Response 502: The billing provider did not answer; nothing changed.

Response 5XX: Server error. The body carries a `requestId` to quote to support.

## POST /v1/account/brix-plan

Choose a plan

Starts a monthly or yearly plan for a workspace billed directly by Brix. Needs a saved card. The first period is charged to the card now; if the payment fails, nothing is created and the response is 402. The plan renews on its end date until it is cancelled.

Auth: Bearer token. Permission: `billing.edit`.

Request body: `application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `cadence` | "monthly" \| "annual" | yes |  |
| `screens` | integer | yes |  |

```bash
curl -X POST "https://api.brixsignage.com/v1/account/brix-plan" \
  -H "Authorization: Bearer $BRIX_API_KEY" \
  -H "Content-Type: application/json"
```

Response 201: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | object |  |
| `data.contract` | BillingTerm | An agreed billing term (a fixed number of screens at a fixed rate for a fixed period). |
| `data.contract.id` | string |  |
| `data.contract.status` | "active" \| "cancelled" \| "awaiting_payment" \| "ended" |  |
| `data.contract.rail` | "chargebee" \| "brix" | Who invoices the term: `brix` (Brix invoices) or `chargebee` (the card subscription). |
| `data.contract.activateOn` | "now" \| "paid" |  |
| `data.contract.poNumber` | string \| null |  |
| `data.contract.invoiceNumber` | string \| null |  |
| `data.contract.invoicePaid` | boolean \| null |  |
| `data.contract.activatedAt` | string \| null |  |
| `data.contract.screens` | integer |  |
| `data.contract.rateCentsPerScreenMonth` | integer |  |
| `data.contract.termMonths` | integer |  |
| `data.contract.schedule` | "upfront" \| "monthly" \| "annual" |  |
| `data.contract.collect` | "card" \| "invoice" |  |
| `data.contract.currency` | string |  |
| `data.contract.startsAt` | string | Date (YYYY-MM-DD). |
| `data.contract.endsAt` | string | Date (YYYY-MM-DD). |
| `data.contract.totalCents` | integer |  |
| `data.contract.monthlyCents` | integer |  |
| `data.contract.termLabel` | string |  |
| `data.contract.scheduleLabel` | string |  |
| `data.contract.invoiceId` | string \| null |  |
| `data.contract.notes` | string \| null |  |
| `data.contract.createdBy` | string \| null |  |
| `data.contract.prior` | object \| null | The plan before the term started. |
| `data.contract.createdAt` | string | ISO-8601 timestamp (UTC). |
| `data.contract.endedAt` | string \| null |  |
| `data.contract.renewal` | "renew" \| "non_renewing" |  |
| `data.contract.renewalInvoiceId` | string \| null |  |
| `data.contract.origin` | "staff" \| "self_serve" | `self_serve` — the customer chose this plan on the Billing page; `staff` — an agreed term set by Brix. |
| `data.contract.next` | object \| null | What the next period starts with, when the customer asked for a change at renewal. |
| `data.invoiceNumber` | string \| null |  |

Response 401: Missing, expired or revoked bearer token.

Response 402: `card_declined` — the first payment failed. Nothing was created.

Response 403: You do not hold the permission for the whole workspace (a grant at one location is not enough).

Response 404: A workspace billed by a partner.

Response 409: `not_brix_billed`, `card_required`, `already_on_plan`, or `payment_required`.

Response 422: Bad `cadence` or `screens`.

Response 503: `price_unavailable`.

Response 5XX: Server error. The body carries a `requestId` to quote to support.

## PUT /v1/account/brix-plan/cadence

Switch plan cadence

Switches the plan between monthly and yearly. The switch takes effect when the current period ends, at the list price of the new cadence.

**Notes.**
- The switch takes effect when the current period ends.

Auth: Bearer token. Permission: `billing.edit`.

Request body: `application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `cadence` | "monthly" \| "annual" | yes |  |

```bash
curl -X PUT "https://api.brixsignage.com/v1/account/brix-plan/cadence" \
  -H "Authorization: Bearer $BRIX_API_KEY" \
  -H "Content-Type: application/json"
```

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | object |  |
| `data.contract` | BillingTerm | An agreed billing term (a fixed number of screens at a fixed rate for a fixed period). |
| `data.contract.id` | string |  |
| `data.contract.status` | "active" \| "cancelled" \| "awaiting_payment" \| "ended" |  |
| `data.contract.rail` | "chargebee" \| "brix" | Who invoices the term: `brix` (Brix invoices) or `chargebee` (the card subscription). |
| `data.contract.activateOn` | "now" \| "paid" |  |
| `data.contract.poNumber` | string \| null |  |
| `data.contract.invoiceNumber` | string \| null |  |
| `data.contract.invoicePaid` | boolean \| null |  |
| `data.contract.activatedAt` | string \| null |  |
| `data.contract.screens` | integer |  |
| `data.contract.rateCentsPerScreenMonth` | integer |  |
| `data.contract.termMonths` | integer |  |
| `data.contract.schedule` | "upfront" \| "monthly" \| "annual" |  |
| `data.contract.collect` | "card" \| "invoice" |  |
| `data.contract.currency` | string |  |
| `data.contract.startsAt` | string | Date (YYYY-MM-DD). |
| `data.contract.endsAt` | string | Date (YYYY-MM-DD). |
| `data.contract.totalCents` | integer |  |
| `data.contract.monthlyCents` | integer |  |
| `data.contract.termLabel` | string |  |
| `data.contract.scheduleLabel` | string |  |
| `data.contract.invoiceId` | string \| null |  |
| `data.contract.notes` | string \| null |  |
| `data.contract.createdBy` | string \| null |  |
| `data.contract.prior` | object \| null | The plan before the term started. |
| `data.contract.createdAt` | string | ISO-8601 timestamp (UTC). |
| `data.contract.endedAt` | string \| null |  |
| `data.contract.renewal` | "renew" \| "non_renewing" |  |
| `data.contract.renewalInvoiceId` | string \| null |  |
| `data.contract.origin` | "staff" \| "self_serve" | `self_serve` — the customer chose this plan on the Billing page; `staff` — an agreed term set by Brix. |
| `data.contract.next` | object \| null | What the next period starts with, when the customer asked for a change at renewal. |
| `data.changed` | boolean |  |
| `data.effectiveAt` | string |  |

Response 401: Missing, expired or revoked bearer token.

Response 403: You do not hold the permission for the whole workspace (a grant at one location is not enough).

Response 404: A workspace billed by a partner.

Response 409: `not_brix_billed` or `no_plan`.

Response 422: Bad `cadence`.

Response 503: `price_unavailable`.

Response 5XX: Server error. The body carries a `requestId` to quote to support.

## GET /v1/account/brix-plan/playing

List screens on the plan

Lists every screen on the plan in the order it was paired. Each screen shows if it plays or waits for payment. Also returns the number of screens the plan pays for.

Auth: Bearer token. Permission: `screen.view`.

```bash
curl "https://api.brixsignage.com/v1/account/brix-plan/playing" \
  -H "Authorization: Bearer $BRIX_API_KEY"
```

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | object |  |
| `data.capacity` | integer \| null |  |
| `data.screens` | array of object |  |
| `data.screens[].id` | string |  |
| `data.screens[].name` | string |  |
| `data.screens[].status` | string |  |
| `data.screens[].lastSeenAt` | string \| null |  |
| `data.screens[].waiting` | boolean |  |
| `data.canChoose` | boolean |  |

Response 401: Missing, expired or revoked bearer token.

Response 403: The token lacks the permission this operation needs (see `x-brix-permission`).

Response 404: A workspace billed by a partner.

Response 5XX: Server error. The body carries a `requestId` to quote to support.

## PUT /v1/account/brix-plan/playing

Choose which screens play

When you have more screens than your plan pays for, choose which screens play. Send exactly as many screens as the plan has. The other screens wait for payment. Nothing is charged.

**Notes.**
- The other screens wait for payment. Nothing is charged.

Auth: Bearer token. Permission: `billing.edit`.

Request body: `application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `screenIds` | array of string | yes |  |

```bash
curl -X PUT "https://api.brixsignage.com/v1/account/brix-plan/playing" \
  -H "Authorization: Bearer $BRIX_API_KEY" \
  -H "Content-Type: application/json"
```

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | object |  |
| `data.playing` | array of string |  |
| `data.waiting` | array of string |  |

Response 401: Missing, expired or revoked bearer token.

Response 403: You do not hold the permission for the whole workspace (a grant at one location is not enough).

Response 404: `screen_not_found`, or a workspace billed by a partner.

Response 409: `not_brix_billed` or `no_plan`.

Response 422: `wrong_count` — choose exactly as many as the plan has.

Response 5XX: Server error. The body carries a `requestId` to quote to support.

## GET /v1/account/brix-plan/pool

Get plan screen counts

For a workspace billed directly by Brix, returns how many screens the plan pays for, how many play, how many wait for payment, the price of one more screen today, and an open request for more screens. The saved card is shown only to a caller who can edit billing. Returns `pool: null` for a workspace that is not billed directly by Brix.

Auth: Bearer token. Permission: `screen.view`.

```bash
curl "https://api.brixsignage.com/v1/account/brix-plan/pool" \
  -H "Authorization: Bearer $BRIX_API_KEY"
```

Response 4XX: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.

Response 5XX: Server error. The body carries a `requestId` to quote to support.

## GET /v1/account/brix-plan/quote

Quote a plan

Returns the list price of a monthly or yearly plan for a screen count, for a workspace billed directly by Brix. Nothing is charged. Returns 409 for a workspace that is not billed directly by Brix.

Auth: Bearer token. Permission: `billing.view`.

Parameters:

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `cadence` | query | "monthly" \| "annual" | yes |  |
| `screens` | query | integer | yes |  |

```bash
curl "https://api.brixsignage.com/v1/account/brix-plan/quote" \
  -H "Authorization: Bearer $BRIX_API_KEY"
```

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | BrixPlanQuote | The price of a plan on Brix's own billing, before anything is charged. |
| `data.cadence` | "monthly" \| "annual" |  |
| `data.screens` | integer |  |
| `data.rateCentsPerScreenMonth` | integer |  |
| `data.termMonths` | integer |  |
| `data.schedule` | "monthly" \| "annual" |  |
| `data.startsAt` | string |  |
| `data.endsAt` | string |  |
| `data.monthlyCents` | integer |  |
| `data.totalCents` | integer | What the first payment is for. |

Response 401: Missing, expired or revoked bearer token.

Response 403: You do not hold the permission for the whole workspace (a grant at one location is not enough).

Response 404: A workspace billed by a partner.

Response 409: `not_brix_billed`.

Response 422: Bad `cadence` or `screens`.

Response 503: `price_unavailable`.

Response 5XX: Server error. The body carries a `requestId` to quote to support.

## PUT /v1/account/brix-plan/screens

Change plan screens

Sets the screen count of the plan. More screens are invoiced now, prorated to the days left in the period, and charged to the saved card. Fewer screens start at the next period and nothing is refunded. The count cannot go below the screens that are running.

**Notes.**
- More screens are charged now, prorated to the days left in the period. Fewer screens start at the next period; nothing is refunded.

Auth: Bearer token. Permission: `billing.edit`.

Request body: `application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `screens` | integer | yes |  |

```bash
curl -X PUT "https://api.brixsignage.com/v1/account/brix-plan/screens" \
  -H "Authorization: Bearer $BRIX_API_KEY" \
  -H "Content-Type: application/json"
```

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | object |  |
| `data.ok` | true |  |
| `data.effect` | "now" \| "renewal" \| "unchanged" |  |
| `data.contract` | BillingTerm | An agreed billing term (a fixed number of screens at a fixed rate for a fixed period). |
| `data.contract.id` | string |  |
| `data.contract.status` | "active" \| "cancelled" \| "awaiting_payment" \| "ended" |  |
| `data.contract.rail` | "chargebee" \| "brix" | Who invoices the term: `brix` (Brix invoices) or `chargebee` (the card subscription). |
| `data.contract.activateOn` | "now" \| "paid" |  |
| `data.contract.poNumber` | string \| null |  |
| `data.contract.invoiceNumber` | string \| null |  |
| `data.contract.invoicePaid` | boolean \| null |  |
| `data.contract.activatedAt` | string \| null |  |
| `data.contract.screens` | integer |  |
| `data.contract.rateCentsPerScreenMonth` | integer |  |
| `data.contract.termMonths` | integer |  |
| `data.contract.schedule` | "upfront" \| "monthly" \| "annual" |  |
| `data.contract.collect` | "card" \| "invoice" |  |
| `data.contract.currency` | string |  |
| `data.contract.startsAt` | string | Date (YYYY-MM-DD). |
| `data.contract.endsAt` | string | Date (YYYY-MM-DD). |
| `data.contract.totalCents` | integer |  |
| `data.contract.monthlyCents` | integer |  |
| `data.contract.termLabel` | string |  |
| `data.contract.scheduleLabel` | string |  |
| `data.contract.invoiceId` | string \| null |  |
| `data.contract.notes` | string \| null |  |
| `data.contract.createdBy` | string \| null |  |
| `data.contract.prior` | object \| null | The plan before the term started. |
| `data.contract.createdAt` | string | ISO-8601 timestamp (UTC). |
| `data.contract.endedAt` | string \| null |  |
| `data.contract.renewal` | "renew" \| "non_renewing" |  |
| `data.contract.renewalInvoiceId` | string \| null |  |
| `data.contract.origin` | "staff" \| "self_serve" | `self_serve` — the customer chose this plan on the Billing page; `staff` — an agreed term set by Brix. |
| `data.contract.next` | object \| null | What the next period starts with, when the customer asked for a change at renewal. |
| `data.chargedCents` | integer |  |
| `data.carriedCents` | integer |  |
| `data.invoiceNumber` | string \| null |  |
| `data.collect` | "card" \| "next_invoice" \| "invoice" | How the added screens were collected. `invoice`: an invoice went out by email and no card was charged. |
| `data.dueAt` | string \| null | When the invoice, or the amount added to the next invoice, is due. |
| `data.audit` | string |  |

Response 401: Missing, expired or revoked bearer token.

Response 402: `card_declined` — the extra screens were not added.

Response 403: You do not hold the permission for the whole workspace (a grant at one location is not enough).

Response 404: A workspace billed by a partner.

Response 409: `not_brix_billed`, `no_plan`, `below_running`, `card_required`, `payment_pending`, or `payment_required`.

Response 422: Bad `screens`.

Response 5XX: Server error. The body carries a `requestId` to quote to support.

## POST /v1/account/brix-plan/screens/estimate

Price a screen change

Returns what a new screen count costs today. More screens are charged now, prorated to the days left in the period. Fewer screens start at the next period. Nothing is changed.

Auth: Bearer token. Permission: `billing.view`.

Request body: `application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `screens` | integer | yes |  |

```bash
curl -X POST "https://api.brixsignage.com/v1/account/brix-plan/screens/estimate" \
  -H "Authorization: Bearer $BRIX_API_KEY" \
  -H "Content-Type: application/json"
```

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | object |  |
| `data.ok` | true |  |
| `data.currentScreens` | integer |  |
| `data.screens` | integer |  |
| `data.effect` | "now" \| "renewal" \| "unchanged" |  |
| `data.chargeCents` | integer |  |
| `data.periodEnds` | string |  |
| `data.collect` | "card" \| "next_invoice" \| "invoice" \| null | How `chargeCents` is collected. `card`: charged to the saved card now. `next_invoice`: added to the next invoice. `invoice`: the account pays by invoice, so an invoice goes out by email and no card is charged. Null when nothing is due now. |
| `data.needsCard` | boolean | True when the account pays by card and no card is saved. The change is refused until a card is saved. |
| `data.dueAt` | string \| null | When the invoice, or the amount added to the next invoice, is due. Null for a card charge. |

Response 401: Missing, expired or revoked bearer token.

Response 403: You do not hold the permission for the whole workspace (a grant at one location is not enough).

Response 404: A workspace billed by a partner.

Response 409: `not_brix_billed` or `no_plan`.

Response 422: Bad `screens`.

Response 5XX: Server error. The body carries a `requestId` to quote to support.
