# Customers and Associates

A common early mistake in B2B modeling is treating "a buyer" as a single resource. commercetools splits the buyer into two: the [Customer](/api/projects/customers.md) is the authentication identity, and the [Associate](/api/projects/business-units.md#associate) is that Customer's membership of a Business Unit, together with the roles they hold there.

Keeping identity separate from authorization is what lets one person act for more than one company, or hold different roles in different parts of the same company, without duplicating their login.

## Customer versus Associate

The two resources answer two different questions.

- **Customer**: who is this person? It holds the authentication credentials (email, password, external identity) and the personal profile. A Customer exists independently of any company.
- **Associate**: what may this person do for this company? It links an existing Customer to a Business Unit and assigns one or more Associate Roles that define their permissions there.

This is the Parallel Layer Principle from Module 1 applied to identity: an Associate **is** a Customer with a B2B membership layered on top. The Associate resource itself is small: it references the Customer and lists that Customer's role assignments within the Business Unit.

```json
{
  "customer": {
    "typeId": "customer",
    "id": "f8a4e2c1-1111-2222-3333-444455556666"
  },
  "associateRoleAssignments": [
    {
      "associateRole": {
        "typeId": "associate-role",
        "key": "buyer"
      },
      "inheritance": "Disabled"
    }
  ]
}
```

Because the Customer and the membership are separate, the same Customer can be added as an Associate to several Business Units. Each membership carries its own role assignments, so a person can be a buyer in one company and an administrator in another while authenticating with a single account.

An Associate can hold up to five role assignments within a single Business Unit. Their effective permissions are the sum of all the roles they hold, a behavior covered in detail on the [Inheritance modes](/learning-model-b2b-commerce/configure-associate-access/inheritance-modes.md) page.

## The provisioning sequence

Adding a buyer to a company is a three-step sequence, and the order matters.

```mermaid
graph LR
 CR[1 Create Associate Role] --> CU[2 Create Customer]
 CU --> AS[3 Add Customer as Associate to Business Unit]
```

1. **Create the Associate Roles** the organization needs. Roles must exist before they can be assigned, so this comes first. Role design is covered on the next page.
2. **Create the Customer** for the person, or reuse an existing one if they already authenticate with commercetools.
3. **Add the Customer as an Associate** to the Business Unit, assigning one or more roles.

The third step uses the `addAssociate` update action on the Business Unit. The `customer` is a reference to the existing Customer, and each entry in `associateRoleAssignments` references an Associate Role by its `key`.

```http
POST /{projectKey}/business-units/key=horizon-hotels HTTP/1.1
Content-Type: application/json

{
  "version": 1,
  "actions": [
    {
      "action": "addAssociate",
      "associate": {
        "customer": {
          "typeId": "customer",
          "id": "f8a4e2c1-1111-2222-3333-444455556666"
        },
        "associateRoleAssignments": [
          {
            "associateRole": {
              "typeId": "associate-role",
              "key": "buyer"
            }
          }
        ]
      }
    }
  ]
}
```

This sequencing is also enforced in the Merchant Center: the Business Unit creation flow requires Associate Roles to exist before you can add Associates. If you plan a Business Unit setup without first defining roles, you will be blocked at the associate-assignment step. This is the setup-sequencing dependency introduced in Module 1.

## Worked example: Horizon Hotels procurement staff

Horizon Hotels is a flat Company (modeled in Module 1) with a small procurement team that reorders a known set of products. Map its people to resources as follows.

- **Maria**, the procurement lead, and **Tom**, a buyer on her team, each need a login. Model each as a **Customer**.
- Both act for Horizon Hotels, so each Customer is added as an **Associate** of the `horizon-hotels` Business Unit.
- Maria also manages her team, so her Associate carries two role assignments: a buyer role and an administrator role. Tom's Associate carries only the buyer role.

Maria and Tom each authenticate as a single Customer, but their Associate memberships give them different permissions inside Horizon Hotels. No resource is duplicated: the roles are defined once and assigned to each Associate as needed.

## Key takeaways

- The Customer is the authentication identity; the Associate is that Customer's membership of a Business Unit with assigned roles.
- An Associate references exactly one Customer, but one Customer can be an Associate of many Business Units.
- Provision in order: create Associate Roles, then the Customer, then add the Customer as an Associate with role assignments.
- The `addAssociate` update action references the Customer and assigns roles by their `key`.
- An Associate can hold up to five role assignments in a single Business Unit, and their permissions are the sum of those roles.

## Related pages

- [Area overview page with navigation](/learning-model-b2b-commerce.md)
- [Previous page: Overview](/learning-model-b2b-commerce/configure-associate-access/overview.md)
- [Next page: Associate Roles and permissions](/learning-model-b2b-commerce/configure-associate-access/associate-roles-and-permissions.md)