# PUT /api/v1/businesses/{business_id}

> Update business

- **Tag:** businesses
- **Operation ID:** `update_business`

## Description

Update business details.

This endpoint supports updating standard business information including:
- Business name, mailbox, properties
- Stripe account ID
- Shopify integration details
- Stripe subscription items (subscription_items)

**Note:** This endpoint updates business details only.

Args:
    business_id (str): The ID of the business to update.
    payload (BusinessUpdateRequest): The updated business details.

Returns:
    BusinessResponse: The updated business details.

## Authentication

Bearer token in `Authorization` header.
Required header: `x-business-id: <business uuid>`.

## Parameters

- `business_id` (path, string, required)

## Request body

Schema: `BusinessUpdateRequest`

- `name` (string) — Business display name.
- `name_aliases` (array · string) — Other names the business goes by (up to 20). find_business matches them as well as the name. Replaces the list; send [] to clear it.
- `logo_url` (string) — URL to business logo/avatar image (https only).
- `default_currency` (string) — Default currency for the business (USD, CAD, AUD, EUR, or GBP).
- `tax_year_end_month` (integer) — Month when the tax/fiscal year ends (1-12).
- `start_date` (string · date) — Date the business started operating (founding date). Distinct from entries_start, which anchors bookkeeping imports.
- `timezone` (string) — IANA time zone the business keeps its days in, e.g. 'America/New_York'. null clears it.
- `accounting_basis` (string) — Default accounting basis for financial reports: 'cash' or 'accrual'. Persisted on the business.
- `mailbox` (string) — Email prefix for bill forwarding.
- `inventory_mode` (string) — Inventory module flavor: 'cpg' exposes the Supply Chain map, production recipes, and landed COGS; 'finished_goods' hides the CPG-only surfaces.
- `ap_approval_enabled` (boolean) — Toggle the AP bill approval workflow for this business. When off (default), bills post directly to 'received'. When on, bills route through 'pending_approval' and only post to the GL once approved.
- `ap_due_date_basis` (string) — Which date vendor-bill payment terms count from for bills that arrive via the AP inbox or upload. 'invoice_date' (default) keeps the due date printed on the invoice. 'received_date' runs the terms (vendor default, else business default, else the span the invoice itself implies) from the day the bill was received, so an invoice dated weeks before it reached you isn't created overdue. Applies to bills ingested after the change; existing bills are not rewritten.
- `ar_subledger_mode` (string) — Where invoice and payment journal entries post the receivable. 'off' (default) uses the one Accounts Receivable ledger. 'per_customer' posts each customer's receivable to its own 'AR - <Customer Name>' child ledger of Accounts Receivable (created on first use, or an existing 'AR - X' ledger is adopted). Applies to entries posted after the change; run POST /ar/subledgers/backfill to move historical entries.
- `auto_link_new_counterparties` (boolean) — Toggle automatic registry linking for NEW customers and vendors (creation hooks, identity layer, nightly sweep). On by default. Turn off to keep new masters unlinked until a person links them; existing links are untouched.
- `auto_rename_counterparties` (boolean) — Toggle automated counterparty re-resolution for transactions that already have a counterparty assigned. On by default. Turn off to stop description edits and the tenant-wide regen from re-deriving counterparty names on existing rows. Manually-set counterparties are always protected regardless of this setting.
- `stripe_payout_sibling_matching` (boolean) — Match a Stripe payout with no deposit in this business to a Stripe-looking deposit in a sibling business of the same firm that has no Stripe account. null (default) = on only when the firm has exactly one such sibling; true/false force it.
- `agent_close_business_day` (integer) — Business day of the month (1-23, -1 = the last one) on which the Agent window starts closing the month that just ended: DayZero sends close.window_opened that day (Fed bank-holiday calendar, New York date). null or 0 turns it off.

## Example request

```json
{
  "accounting_basis": "accrual",
  "default_currency": "USD",
  "name": "Acme Coffee Roasters",
  "tax_year_end_month": 12
}
```

## Responses

### 200 — Successful Response

Schema: `SuccessEnvelope_BusinessResponse_`

- `success` (boolean)
- `message` (string)
- `code` (string)
- `data` (BusinessResponse)

### 401 — Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business

Schema: `ErrorResponse`

- `error` (string · required) — Error category: `validation_error`, `unauthorized`, `forbidden`, `not_found`, `conflict`, `rate_limited`, `server_error`, or `service_unavailable`.
- `message` (string · required) — Human-readable explanation, safe to show to end users.
- `code` (string · required) — Stable machine-readable code in `CATEGORY_NNN` form (e.g. `NOT_FOUND_006`, `AUTH_010`, `GEN_002`).
- `request_id` (string) — Correlation id for support requests. Echoes the `x-request-id` request header when one was supplied.
- `errors` (object) — Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

### 403 — Forbidden - Insufficient permissions

Schema: `ErrorResponse`

- `error` (string · required) — Error category: `validation_error`, `unauthorized`, `forbidden`, `not_found`, `conflict`, `rate_limited`, `server_error`, or `service_unavailable`.
- `message` (string · required) — Human-readable explanation, safe to show to end users.
- `code` (string · required) — Stable machine-readable code in `CATEGORY_NNN` form (e.g. `NOT_FOUND_006`, `AUTH_010`, `GEN_002`).
- `request_id` (string) — Correlation id for support requests. Echoes the `x-request-id` request header when one was supplied.
- `errors` (object) — Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

### 422 — Validation Error

Schema: `ErrorResponse`

- `error` (string · required) — Error category: `validation_error`, `unauthorized`, `forbidden`, `not_found`, `conflict`, `rate_limited`, `server_error`, or `service_unavailable`.
- `message` (string · required) — Human-readable explanation, safe to show to end users.
- `code` (string · required) — Stable machine-readable code in `CATEGORY_NNN` form (e.g. `NOT_FOUND_006`, `AUTH_010`, `GEN_002`).
- `request_id` (string) — Correlation id for support requests. Echoes the `x-request-id` request header when one was supplied.
- `errors` (object) — Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

## Code samples

### cURL

```bash
curl -X PUT 'https://api.ondayzero.com/api/v1/businesses/{business_id}' \
  -H 'Authorization: Bearer dz_your_token' \
  -H 'x-business-id: YOUR_BUSINESS_ID' \
  -H 'Content-Type: application/json' \
  -d '{
  "accounting_basis": "accrual",
  "default_currency": "USD",
  "name": "Acme Coffee Roasters",
  "tax_year_end_month": 12
}'
```

### JavaScript

```javascript
const response = await fetch('https://api.ondayzero.com/api/v1/businesses/{business_id}', {
  method: 'PUT',
  headers: {
    Authorization: 'Bearer dz_your_token',
    'x-business-id': 'YOUR_BUSINESS_ID',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "accounting_basis": "accrual",
  "default_currency": "USD",
  "name": "Acme Coffee Roasters",
  "tax_year_end_month": 12
}),
});
const data = await response.json();
```

### Python

```python
import httpx

headers = {
    "Authorization": "Bearer dz_your_token",
    "x-business-id": "YOUR_BUSINESS_ID",
}

payload = {'accounting_basis': 'accrual',
 'default_currency': 'USD',
 'name': 'Acme Coffee Roasters',
 'tax_year_end_month': 12}

response = httpx.put("https://api.ondayzero.com/api/v1/businesses/{business_id}", headers=headers, json=payload)
data = response.json()
```

## See also

- HTML version: https://www.ondayzero.com/docs/reference/businesses/update-business
- OpenAPI slice: https://www.ondayzero.com/docs/reference/businesses/update-business/openapi.json
- Other endpoints in **businesses**: https://www.ondayzero.com/docs/reference/businesses (markdown bundle: https://www.ondayzero.com/docs/reference/businesses.md, OpenAPI: https://www.ondayzero.com/docs/reference/businesses/openapi.json)
- Endpoint catalog: https://www.ondayzero.com/docs/reference/index.md
