Billing groups API
Billing groups endpoints in the Brix REST API: 6 operations (GET, POST, PATCH, DELETE). Each lists its path, auth, required permission and a curl example.
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.
GET /v1/billing-groupsPOST /v1/billing-groupsGET /v1/billing-groups/{id}PATCH /v1/billing-groups/{id}DELETE /v1/billing-groups/{id}POST /v1/billing-groups/{id}/screens
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/billing-groups
Returns the workspace's billing groups (who pays for which screens), each with its current count of billable screens.
Notes.
- Sorted by name; not paginated. Unlike the single read, list rows have no createdAt / updatedAt.
curl "https://api.brixsignage.com/v1/billing-groups" \
-H "Authorization: Bearer $BRIX_API_KEY"Response 200: Success.
| Field | Type | Description |
|---|---|---|
data | array of object | |
data[].id | string | |
data[].name | string | |
data[].financeContactName | string | null | |
data[].financeContactEmail | string | null | Where this group's invoices go. |
data[].chargebeeCustomerId | string | null | The billing customer linked by Brix; null until linked. |
data[].chargebeeSubscriptionId | string | null | The subscription linked by Brix; null until linked. |
data[].subscriptionStatus | string | null | |
data[].paymentTermsDays | integer | null | Net payment terms in days; null = the workspace default. |
data[].screenCount | integer | Screens billed to this group. |
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/billing-groups
Creates a billing group with a name and finance contact. Connecting it to an account with the billing provider is a separate step; one is never created automatically here. Notes. - The group bills nothing until Brix links it to a billing account.
Request body: application/json
| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | |
financeContactName | string | no | |
financeContactEmail | string | no | Stored in lower case. |
paymentTermsDays | number | no | Net terms in days; rounded. Not range-checked on create. |
curl -X POST "https://api.brixsignage.com/v1/billing-groups" \
-H "Authorization: Bearer $BRIX_API_KEY" \
-H "Content-Type: application/json"Response 201: Success.
| Field | Type | Description |
|---|---|---|
data | BillingGroup | A group of screens billed separately (its own invoice and finance contact). |
data.id | string | |
data.name | string | |
data.financeContactName | string | null | |
data.financeContactEmail | string | null | Where this group's invoices go. |
data.chargebeeCustomerId | string | null | The billing customer linked by Brix; null until linked. |
data.chargebeeSubscriptionId | string | null | The subscription linked by Brix; null until linked. |
data.subscriptionStatus | string | null | |
data.paymentTermsDays | integer | null | Net payment terms in days; null = the workspace default. |
data.screenCount | integer | Screens billed to this group. |
data.createdAt | string | ISO-8601 timestamp (UTC). |
data.updatedAt | string | ISO-8601 timestamp (UTC). |
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: name missing.
Response 5XX: Server error. The body carries a requestId to quote to support.
GET /v1/billing-groups/{id}
Returns one billing group by id.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | Billing group id. |
curl "https://api.brixsignage.com/v1/billing-groups/{id}" \
-H "Authorization: Bearer $BRIX_API_KEY"Response 200: Success.
| Field | Type | Description |
|---|---|---|
data | BillingGroup | A group of screens billed separately (its own invoice and finance contact). |
data.id | string | |
data.name | string | |
data.financeContactName | string | null | |
data.financeContactEmail | string | null | Where this group's invoices go. |
data.chargebeeCustomerId | string | null | The billing customer linked by Brix; null until linked. |
data.chargebeeSubscriptionId | string | null | The subscription linked by Brix; null until linked. |
data.subscriptionStatus | string | null | |
data.paymentTermsDays | integer | null | Net payment terms in days; null = the workspace default. |
data.screenCount | integer | Screens billed to this group. |
data.createdAt | string | ISO-8601 timestamp (UTC). |
data.updatedAt | string | ISO-8601 timestamp (UTC). |
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: No such group in this workspace.
Response 5XX: Server error. The body carries a requestId to quote to support.
PATCH /v1/billing-groups/{id}
Updates a billing group's name, finance contact, or invoice terms.
Notes.
- paymentTermsDays is range-checked here (1–365) but not on create.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | Billing group id. |
Request body: application/json
| Field | Type | Required | Description |
|---|---|---|---|
name | string | no | |
financeContactName | string | null | no | |
financeContactEmail | string | null | no | |
paymentTermsDays | number | null | no | 1–365, or null to use the workspace default. |
curl -X PATCH "https://api.brixsignage.com/v1/billing-groups/{id}" \
-H "Authorization: Bearer $BRIX_API_KEY" \
-H "Content-Type: application/json"Response 200: Success.
| Field | Type | Description |
|---|---|---|
data | BillingGroup | A group of screens billed separately (its own invoice and finance contact). |
data.id | string | |
data.name | string | |
data.financeContactName | string | null | |
data.financeContactEmail | string | null | Where this group's invoices go. |
data.chargebeeCustomerId | string | null | The billing customer linked by Brix; null until linked. |
data.chargebeeSubscriptionId | string | null | The subscription linked by Brix; null until linked. |
data.subscriptionStatus | string | null | |
data.paymentTermsDays | integer | null | Net payment terms in days; null = the workspace default. |
data.screenCount | integer | Screens billed to this group. |
data.createdAt | string | ISO-8601 timestamp (UTC). |
data.updatedAt | string | ISO-8601 timestamp (UTC). |
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: No such group.
Response 422: Empty name, or paymentTermsDays outside 1–365.
Response 5XX: Server error. The body carries a requestId to quote to support.
DELETE /v1/billing-groups/{id}
Soft-deletes a billing group. Returns 409 if any screens are still billed to it; move or remove those screens first.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | Billing group id. |
curl -X DELETE "https://api.brixsignage.com/v1/billing-groups/{id}" \
-H "Authorization: Bearer $BRIX_API_KEY"Response 200: Success.
| Field | Type | Description |
|---|---|---|
data | object | |
data.id | string | |
data.deleted | true |
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: No such group.
Response 409: group_in_use: screens still bill to it; move them first (PATCH /v1/screens/:id billingGroupId).
Response 5XX: Server error. The body carries a requestId to quote to support.
POST /v1/billing-groups/{id}/screens
Assigns a batch of screens to a billing group. This updates the destination group, every group the screens are moving from, and the workspace subscription, so screen counts and billing stay in sync.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | Billing group id. |
Request body: application/json
| Field | Type | Required | Description |
|---|---|---|---|
screenIds | array of string | yes | Up to 500 are read; more are ignored. Ids that are not live screens are skipped. |
curl -X POST "https://api.brixsignage.com/v1/billing-groups/{id}/screens" \
-H "Authorization: Bearer $BRIX_API_KEY" \
-H "Content-Type: application/json"Response 200: Success.
| Field | Type | Description |
|---|---|---|
data | object | |
data.id | string | |
data.assigned | integer | Screens moved into the group. |
data.skipped | integer | Ids not moved (unknown, or already in the group). |
data.screenCount | integer |
Response 401: Missing, expired or revoked bearer token.
Response 403: You lack billing.edit at one of the screens' locations (the response names them in screenIds); nothing changes. Also: You do not hold the permission for the whole workspace (a grant at one location is not enough).
Response 404: No such group, or none of the ids is a live screen.
Response 422: screenIds missing or empty.
Response 5XX: Server error. The body carries a requestId to quote to support.