Businesses

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:

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

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

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

Filtering