Client billing profile

Client billing profile operations in the Hlix API.

The client billing profile holds the agency’s own billing identity — the details that appear on an invoice it issues.

See the OpenAPI document for schemas and operation IDs.

Prerequisites

Protected operations require an API key in x-api-key or a browser session cookie; some actions require a verified user session
Tenant-scoped operations use X-Organization-Id; browser sessions can use their active workspace. Discovery and personal-workspace bootstrap do not require an active workspace
The base URL for your deployment, https://server.hlix.ai by default

Method	Path	Operation
`DELETE`	`/v1/api/client-billing/profile`	Remove the workspace’s billing identity
`GET`	`/v1/api/client-billing/profile`	Get the workspace’s billing identity
`PUT`	`/v1/api/client-billing/profile`	Replace the workspace’s billing identity
`GET`	`/v1/api/client-billing/profile/logo`	Download the workspace’s logo

DELETE /v1/api/client-billing/profile · operation ID deleteAgencyBillingProfile

Parameters

Name	In	Required	Type	Description
`X-Organization-Id`	header	no	string	The workspace (organization) to act in. Omitted, the session’s active organization is used.

Responses

Status	Body	Description
`200`	AgencyBillingProfileCleared	Removed. New invoices are issued unbranded; ones already issued keep the identity frozen onto them.
`400`	ApiError	The request named no active organization.
`401`	ApiError	No valid session or API key.
`403`	ApiError	The caller is a `member`. Changing the legal entity every customer is billed by is restricted to owners and admins.
`404`	ApiError	No billing profile is set.

GET /v1/api/client-billing/profile · operation ID getAgencyBillingProfile

Parameters

Name	In	Required	Type	Description
`X-Organization-Id`	header	no	string	The workspace (organization) to act in. Omitted, the session’s active organization is used.

Responses

Status	Body	Description
`200`	AgencyBillingProfileState	The profile, or `null` if none was ever saved. `branded` says whether the workspace’s plan puts it on invoices — an unbranded workspace still issues complete, correct documents.
`400`	ApiError	The request named no active organization.
`401`	ApiError	No valid session or API key.
`403`	ApiError	The caller is a `client` collaborator. The agency’s billing identity is agency-only, reads included.
`404`	ApiError	The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist.

PUT /v1/api/client-billing/profile · operation ID upsertAgencyBillingProfile

Parameters

Name	In	Required	Type	Description
`X-Organization-Id`	header	no	string	The workspace (organization) to act in. Omitted, the session’s active organization is used.

Request body — application/json, UpsertBillingProfile (required)

Property	Type	Required	Notes
`address`	string	yes	min length 1, max length 1000
`brandColor`	string \| null	no
`contactEmail`	string (email) \| null	no
`defaultPaymentTerms`	string \| null	no
`invoiceFooter`	string \| null	no
`legalName`	string	yes	min length 1, max length 200
`logo`	object \| null	no
`taxId`	string \| null	no

Responses

Status	Body	Description
`200`	AgencyBillingProfileState	The saved billing profile. This PUT replaces the profile: omitted optional fields are cleared, including a previously stored logo.
`400`	ValidationError \| ApiError	The JSON body failed schema validation (`ValidationError`), the request named no active organization, or the logo is not the image format it claims to be — the bytes are decoded, not trusted, and this route reads the file header (`ApiError`).
`401`	ApiError	No valid session or API key.
`403`	ApiError	The caller is a `member`. Changing the legal entity every customer is billed by is restricted to owners and admins.
`404`	ApiError	The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist.

GET /v1/api/client-billing/profile/logo · operation ID getAgencyBillingProfileLogo

Parameters

Name	In	Required	Type	Description
`X-Organization-Id`	header	no	string	The workspace (organization) to act in. Omitted, the session’s active organization is used.

Responses

Status	Body	Description
`200`	string (binary)	The stored image. The `Content-Type` is the format recorded in the database, not one the uploader asserted, and `X-Content-Type-Options: nosniff` accompanies it.
`400`	ApiError	The request named no active organization.
`401`	ApiError	No valid session or API key.
`403`	ApiError	The caller is a `client` collaborator. The agency’s billing identity is agency-only, reads included.
`404`	ApiError	No logo is set for this workspace.

The response table for each operation lists its documented errors. Common status codes include:

400 — the body failed schema validation, or the request named no active organization. A ValidationError body carries the failing fields; an ApiError body carries only error.
401 — no valid session or API key.
403 — authenticated, but not a member of the named organization, or a client collaborator without the required access.
404 — check the resource ID and your access to the selected Workspace.
409 — the expected revision or state is stale, or another operation currently owns the transition.
500 — the operation failed server-side. Retry only where an idempotency key makes that safe.