> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anny.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Businesses

Manage B2B customer entities. Businesses group customers and enable consolidated billing via [Customer Balances](/developers/guides/admin/customer-balances).

For general conventions, see [JSON-API Conventions](/developers/guides/json-api-conventions). For authentication, see [Authentication](/developers/guides/authentication).

***

## Prerequisites

* A valid Bearer token with admin access
* Organization context (`?o={organization_id}`)

***

## Overview

A **Business** represents a company or organization. Customers can be assigned to a business — either manually by an admin or automatically during checkout based on the customer's email domain.

Key use cases:

* Group customers by employer for B2B billing
* Collect business-level billing addresses and VAT IDs
* Consolidate invoices under a single business balance

***

## Business vs. Business Account

Similar to the Customer/CustomerAccount distinction, the platform separates business data into two scopes:

| Entity              | Scope                  | Purpose                                                                                                                                                                                         |
| ------------------- | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Business**        | Per-organization       | An org-level record holding billing info, customers, and balances. Managed by admins via the API.                                                                                               |
| **BusinessAccount** | Global (platform-wide) | A cross-organization identity that links Business records across multiple organizations. Enables deduplication — the same company booking with different providers is recognized as one entity. |

A single company may have multiple `Business` records (one per organization), all linked to the same `BusinessAccount` via domain and name matching. The `BusinessAccount` is managed automatically by the platform and is not directly accessible through the admin API.

***

## Creating a Business

```http theme={null}
POST /api/v1/businesses?o={org_id}

{
  "data": {
    "type": "businesses",
    "attributes": {
      "name": "Acme Corp",
      "billing_email": "billing@acme.com",
      "domain": "acme.com",
      "vat_id": "DE123456789"
    }
  }
}
```

### Key Attributes

| Attribute          | Type   | Description                                                     |
| ------------------ | ------ | --------------------------------------------------------------- |
| `name`             | string | Business name (required)                                        |
| `brand_name`       | string | Optional short brand name (auto-generated from `name` if empty) |
| `domain`           | string | Email domain for automatic customer assignment                  |
| `billing_email`    | string | Billing contact email                                           |
| `vat_id`           | string | VAT identification number                                       |
| `notes`            | string | Internal notes (admin-only visibility)                          |
| `custom_entry_map` | object | Custom field entries keyed by field UUID                        |

***

## Automatic Assignment via Domain

During checkout, customers are automatically assigned to a business when **both** conditions are met:

1. **Domain match** — the customer's email domain matches the business's `domain` (e.g., `jane@acme.com` → `acme.com`). Generic email providers (gmail.com, outlook.com, etc.) are excluded.
2. **Name match** — the company name provided at checkout matches the business name after normalization (legal form suffixes like "GmbH", "Inc", "Ltd" are stripped before comparison).

Both criteria must match to prevent false grouping — e.g., two different companies sharing the same email domain (co-working spaces, shared tenants) are kept separate because their names differ.

If only the name matches (generic email domain), the system falls back to name-based deduplication without cross-organization linking.

This assignment also triggers cross-organization deduplication via **BusinessAccounts** — businesses with the same domain and normalized name across different organizations are linked automatically.

***

## Reading Businesses

### List All

```http theme={null}
GET /api/v1/businesses?o={org_id}
```

### Search by Name

```http theme={null}
GET /api/v1/businesses?o={org_id}&filter[search]=acme
```

Searches across name, domain, and VAT ID.

### Include Relationships

```http theme={null}
GET /api/v1/businesses/{uuid}?o={org_id}&include=billing_address,customers,customer_balances,logo_image,payment_setup
```

***

## Including Business on Other Resources

The `business` relationship is available as an include on several resources:

### On Customers

```http theme={null}
GET /api/v1/customers?o={org_id}&include=business,business.logo_image,business.billing_address
```

### On Orders

```http theme={null}
GET /api/v1/orders?o={org_id}&include=customer.business,customer.business.logo_image
```

### On Plan Subscriptions

```http theme={null}
GET /api/v1/plan-subscriptions?o={org_id}&include=customer.business,customer.business.custom_entries.field
```

### On Bookings

```http theme={null}
GET /api/v1/bookings/{id}?o={org_id}&include=customer.business
```

***

## Updating a Business

```http theme={null}
PATCH /api/v1/businesses/{uuid}?o={org_id}

{
  "data": {
    "type": "businesses",
    "id": "{uuid}",
    "attributes": {
      "name": "Acme Corporation",
      "billing_email": "invoices@acme.com"
    }
  }
}
```

***

## Deleting a Business

```http theme={null}
DELETE /api/v1/businesses/{uuid}?o={org_id}
```

Customers previously linked to the deleted business will be unlinked (their `business` relationship becomes `null`).

***

## Sorting

| Parameter    | Description                   |
| ------------ | ----------------------------- |
| `name`       | Alphabetical by business name |
| `created_at` | By creation date              |

***

## Filtering

| Filter                | Description                             |
| --------------------- | --------------------------------------- |
| `filter[ids]`         | Comma-separated UUIDs                   |
| `filter[exclude_ids]` | Exclude specific UUIDs                  |
| `filter[name]`        | Exact name match                        |
| `filter[search]`      | Full-text search (name, domain, VAT ID) |