Businesses - anny

Manage B2B customer entities. Businesses group customers and enable consolidated billing via Customer Balances. For general conventions, see JSON-API Conventions. For authentication, see 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

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:

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.
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

GET /api/v1/businesses?o={org_id}

Search by Name

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

Searches across name, domain, and VAT ID.

Include Relationships

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

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

On Orders

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

On Plan Subscriptions

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

On Bookings

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

Updating a Business

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

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)

​Prerequisites

​Overview

​Business vs. Business Account

​Creating a Business

​Key Attributes

​Automatic Assignment via Domain

​Reading Businesses

​List All

​Search by Name

​Include Relationships

​Including Business on Other Resources

​On Customers

​On Orders

​On Plan Subscriptions

​On Bookings

​Updating a Business

​Deleting a Business

​Sorting

​Filtering