# 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`](/api/openapi/) 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](#remove-the-workspaces-billing-identity) |
| `GET` | `/v1/api/client-billing/profile` | [Get the workspace's billing identity](#get-the-workspaces-billing-identity) |
| `PUT` | `/v1/api/client-billing/profile` | [Replace the workspace's billing identity](#replace-the-workspaces-billing-identity) |
| `GET` | `/v1/api/client-billing/profile/logo` | [Download the workspace's logo](#download-the-workspaces-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 reference](/api/reference/)
  [API & OpenAPI](/api/openapi/)
  [TypeScript SDK](/sdk/typescript/)
  [CLI reference](/reference/cli/)