Skip to content

Granting a User Role Based on a Product Purchase

Based on the discussion in drupal.org issue #3477420, this guide walks through creating an ECA model that automatically grants a user role when a customer purchases a specific product. This is a common requirement for membership sites, gated content, or any scenario where purchasing a product should unlock additional permissions.

Prerequisites

Before you begin, make sure the following modules are installed and enabled:

1
2
composer require drupal/eca drupal/eca_commerce drupal/bpmn_io
drush en -y eca eca_commerce eca_content eca_ui bpmn_io

You should also have:

  • At least one Commerce product (the "membership" product or similar)
  • A Drupal role to assign (e.g. member)

Understanding the Right Event

A common mistake is to use the Checkout: Completion event. This does not work reliably for anonymous checkout flows, because the user account may not yet be created at the time that event fires.

The correct event to use is Order: Assign order. This event fires when Commerce assigns an order to a customer, which happens after the user account has been created (for anonymous checkouts) or is already available (for authenticated users). It provides two key tokens:

Token Description
[commerce_customer] The customer — a Drupal user entity.
[commerce_order] The order entity.

This works for both scenarios:

  • Anonymous checkout with the "Create a new account for an anonymous order" setting enabled — the user is created before this event fires.
  • Authenticated users who are already logged in when purchasing.

Basic Approach: Grant a Role on Any Purchase

If you want to grant a role whenever any order is assigned to a customer (regardless of which product was purchased), the model is straightforward.

Step 1. Create a New ECA Model

Navigate to Configuration > Workflow > ECA and click Add new model. Give it a name, e.g. "Grant role on product purchase".

Step 2. Add the Start Event

  1. Drag a start event (circle) onto the canvas.
  2. In the properties panel, select the event Order: Assign order (eca_commerce_order_assign).

Step 3. Add the Action to Grant the Role

  1. Click the start event and append a new task.
  2. Select the action Add a role to the selected users.

  3. Configure the fields:

    Role
    Select the role you want to grant, e.g. member.
    Entity
    Enter commerce_customer (without brackets). This is the token provided by the event, representing the user who placed the order.

  4. Save the model.

That is all you need for the basic case. When a customer completes an order, ECA will automatically assign the chosen role to their account.

Advanced Approach: Grant a Role Only for a Specific Product

In many cases, you only want to grant the role when a particular product has been ordered — not for every purchase. Since the "Order: Assign order" event provides the full order entity, you can loop through the order items and check whether the target product is among them.

Step 1. Create the Start Event

Same as above: use the Order: Assign order event.

Step 2. Get the Order Items

  1. Append a task to the start event.
  2. Select the action Entity: get field value.

  3. Configure:

    Field name
    order_items — this is the field on the Commerce order entity that references its order items.
    Token name
    order_items_list
    Entity
    commerce_order

This stores the list of order item entities into the token order_items_list.

Step 3. Loop Through the Order Items

  1. Append a task to the previous action.
  2. Select the action Token: set value or use the looping mechanism that fits your ECA version.

The recommended approach is to use the Entity: compare field value condition on each order item. For each item in the loop, compare the purchased_entity field against the product variation ID you are looking for.

Alternative: List contains item

If you know the exact product variation ID, you may also be able to use the List: contains item condition to check whether the order items list contains the target product. This depends on the data format returned by Commerce for the order items reference field.

Step 4. Add a Condition to Check the Product

After obtaining each order item (e.g. via a loop), add a gateway with a condition:

  1. Select the condition Entity: compare field value.

  2. Configure:

    Field name
    purchased_entity — this references the product variation on the order item.
    Expected value
    The ID of the product variation that should trigger the role grant, e.g. 2.
    Operator
    equals
    Entity
    The current order item token from your loop.

Step 5. Grant the Role (Conditional)

Connect the "yes" path from the condition gateway to the role assignment action:

  1. Select Add a role to the selected users.
  2. Set the Role to the desired role (e.g. member).
  3. Set Entity to commerce_customer.

Save the model.

Summary

Component Plugin / Token
Event Order: Assign order
Customer token [commerce_customer]
Order token [commerce_order]
Action (role) Add a role to the selected users
Condition (product check) Entity: compare field value
Action (get items) Entity: get field value

Tips

  • Do not use "Checkout: Completion" for anonymous checkout flows. The user may not exist yet at that point.
  • "Order: Assign order" fires when Commerce assigns the order to a user. For anonymous checkouts, this happens after the user account is created.
  • If you need to check for a specific product, loop through the order items and compare the purchased_entity field against the target product variation ID.
  • The [commerce_customer] token is a full Drupal user entity, so you can use it directly in the "Entity" field of user-related actions.
  • For debugging, enable ECA logging under Configuration > Workflow > ECA > Settings to trace which events fire and which tokens are available.