# Set billing details

`PUT https://evohub.io/api/v1/billing/profile`

Part of the [Billing API](https://docs.evohub.io/billing.md) reference · operationId `setBillingProfile`.

Replaces the billing details as a whole — send every field, not
just the ones that changed. The address is written as given and
replaces any address taken from a card. Surrounding spaces are
trimmed and the country is upper-cased.

- `legal_name`, `email`, `address.line1`, `address.city` and a
  two-letter `address.country` are required; otherwise **400**
  `INCOMPLETE_PROFILE`, whose message names what is missing.
- `entity_type` is `business` or `individual`; anything else is
  taken as `business`. An individual has no tax number: one on file
  is removed and `tax_id` is ignored.
- `tax_id` replaces the number on file, filed under the type its
  country uses; an empty value removes it. A number for a country
  where none can be filed is **400** `TAX_ID_NOT_SUPPORTED`.

Answers with the details as saved.

Requires the `billing:profile:write` scope.

## Authorization

Any one of:

- `bearerKey`
- `headerKey`

Where:

- `bearerKey`: HTTP Bearer — An EvoHub API key (`evohub_…`) as a bearer token.
- `headerKey`: API key in the header `X-API-Key` — An EvoHub API key (`evohub_…`).

## Request body (required)

Content type: `application/json`

Type: `BillingProfileRequest`

- `entity_type` (string, one of `business`, `individual`, default `business`)
- `legal_name` (string, required)
- `email` (string, required)
- `address` (object, required)
  - `line1` (string, required)
  - `line2` (string)
  - `city` (string, required)
  - `state` (string)
  - `postal_code` (string)
  - `country` (string, required, min length 2, max length 2)
- `tax_id` (string): Ignored for an individual. `""` removes the number on file.

## Responses

### 200 — The billing details as saved.

Content type: `application/json`

Type: `object`

- `data` (BillingProfile)
  - `entity_type` (string, one of `business`, `individual`)
  - `legal_name` (string): The company or person invoices are made out to.
  - `email` (string): Where invoices and receipts are sent.
  - `address` (BillingAddress)
    - `line1` (string)
    - `line2` (string): Left out when empty.
    - `city` (string)
    - `state` (string): Left out when empty.
    - `postal_code` (string)
    - `country` (string, example `IE`): Two-letter country code (ISO 3166-1 alpha-2).
  - `tax_id` (string)
  - `tax_id_type` (string): What the number is filed as, e.g. `eu_vat`. Left out when there is no number.
  - `tax_id_supported` (boolean): Whether a tax number can be filed for this country and entity type.
  - `complete` (boolean): Whether enough is on file for a proper invoice.

### 400 — The body is not JSON (`INVALID_BODY`), a required field is missing (`INCOMPLETE_PROFILE`), a tax number was given for a country where none can be filed (`TAX_ID_NOT_SUPPORTED`), or the details were not accepted — usually a tax number that does not match its country's format (`PROFILE_REJECTED`).

Content type: `application/json`

Type: `Error`

- `error` (object, required)
  - `code` (string, required, example `STATEMENT_NOT_FOUND`)
  - `message` (string, required, example `No statement for that period.`)
  - `request_id` (string)

### 401 — No API key was sent, or it is unknown, revoked or expired (`UNAUTHORIZED`).

Content type: `application/json`

Type: `Error`

- `error` (object, required)
  - `code` (string, required, example `STATEMENT_NOT_FOUND`)
  - `message` (string, required, example `No statement for that period.`)
  - `request_id` (string)

### 403 — The key lacks the scope this endpoint needs (`FORBIDDEN`).

Content type: `application/json`

Type: `Error`

- `error` (object, required)
  - `code` (string, required, example `STATEMENT_NOT_FOUND`)
  - `message` (string, required, example `No statement for that period.`)
  - `request_id` (string)

### 429 — Too many requests (`RATE_LIMITED`). Wait for `Retry-After` seconds.

Headers:

- `Retry-After` (integer): Seconds to wait before retrying.

Content type: `application/json`

Type: `Error`

- `error` (object, required)
  - `code` (string, required, example `STATEMENT_NOT_FOUND`)
  - `message` (string, required, example `No statement for that period.`)
  - `request_id` (string)

### 503 — Payments are not enabled on this environment (`PAYMENTS_DISABLED`).

Content type: `application/json`

Type: `Error`

- `error` (object, required)
  - `code` (string, required, example `STATEMENT_NOT_FOUND`)
  - `message` (string, required, example `No statement for that period.`)
  - `request_id` (string)

## Example request

```bash
curl -X PUT 'https://evohub.io/api/v1/billing/profile' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <TOKEN>' \
  -d '{
  "email": "finance@acme.example",
  "tax_id": "IE1234567T",
  "address": {
    "city": "Dublin",
    "line1": "1 Market Street",
    "country": "IE",
    "postal_code": "D02 XY45"
  },
  "legal_name": "Acme Ltd",
  "entity_type": "business"
}'
```