Learning PathModule

Customers and Associates

Distinguish the Customer identity from the Associate that scopes it to a Business Unit, and provision both in the correct order.

Ask about this Page
Copy for LLM
View as Markdown

After completing this page, you should be able to:

  • Distinguish between the Customer and Associate resources and explain why they are separate.

  • Describe the provisioning sequence for adding a buyer to a Business Unit.

  • Identify the role assignments an Associate carries within a Business Unit.

A common early mistake in B2B modeling is treating "a buyer" as a single resource. commercetools splits the buyer into two: the Customer is the authentication identity, and the 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.
{
  "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 page.

The provisioning sequence

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

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

Test your knowledge