Client billing profile

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

Generated from contract version 1.0.0 — the same document /v1/api/openapi.json serves.

Prerequisites

• An API key in x-api-key, or a browser session cookie
• X-Organization-Id naming the workspace to act in, unless the session already has an active one
• The base URL for your deployment, https://server.hlix.ai by default

Operations

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

Remove the workspace’s billing identity

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 the workspace’s billing identity

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.

Replace the workspace’s billing identity

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 profile. A PUT, not a PATCH: an omitted optional field is CLEARED, which is the only way to remove a 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.

Download the workspace’s logo

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.

If a request fails

These apply to every operation on this page.

• 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 — no such resource in this workspace. Absent and not-visible are deliberately the same answer; do not infer cross-tenant existence from it.
• 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.

Next steps

API referenceEvery resource in the published contract, and what is deliberately not in it.

API & OpenAPIDownload the contract, generate a client, and read the compatibility policy.

TypeScript SDKAuth, retries, typed errors, uploads and streaming, already built.

CLI referenceThe same operations from a terminal, with a stable JSON envelope.