Account API (part 1 of 4)
Account endpoints in the Brix REST API, part 1 of 4: 13 operations from /v1/account, each with auth, permission and curl.
View as Markdown · For AI agents: the full docs index is at /llms.txt
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, Errors and rate limits and Pagination.
Account is split into 4 pages: part 1 (/v1/account to /v1/account/brix-plan/screens/estimate), part 2 (/v1/account/brix-plan/screens/request to /v1/account/location-payment), part 3 (/v1/account/location-payment to /v1/account/payment-card/complete), part 4 (/v1/account/payment-card/setup to /v1/account/upgrade-annual/estimate).
GET /v1/accountPOST /v1/account/about-youGET /v1/account/billing-addressPUT /v1/account/billing-addressPOST /v1/account/billing-modePOST /v1/account/brix-planPUT /v1/account/brix-plan/cadenceGET /v1/account/brix-plan/playingPUT /v1/account/brix-plan/playingGET /v1/account/brix-plan/poolGET /v1/account/brix-plan/quotePUT /v1/account/brix-plan/screensPOST /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
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).
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
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.
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. |
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
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.
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
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.
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 |
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
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.
Request body: application/json
| Field | Type | Required | Description |
|---|---|---|---|
mode | "auto" | "invoice" | yes |
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
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.
Request body: application/json
| Field | Type | Required | Description |
|---|---|---|---|
cadence | "monthly" | "annual" | yes | |
screens | integer | yes |
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
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.
Request body: application/json
| Field | Type | Required | Description |
|---|---|---|---|
cadence | "monthly" | "annual" | yes |
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
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.
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
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.
Request body: application/json
| Field | Type | Required | Description |
|---|---|---|---|
screenIds | array of string | yes |
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
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.
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
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.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
cadence | query | "monthly" | "annual" | yes | |
screens | query | integer | yes |
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
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.
Request body: application/json
| Field | Type | Required | Description |
|---|---|---|---|
screens | integer | yes |
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
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.
Request body: application/json
| Field | Type | Required | Description |
|---|---|---|---|
screens | integer | yes |
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.