Migrate to multiple Customer Groups

You can assign up to 500 Customer Groups to a Customer BETA. While the Customer customerGroup field supports assigning only one Customer Group for a Customer, the customerGroupAssignments field BETA supports assigning multiple Customer Groups for a Customer. You can use both fields concurrently for existing projects. However, for new projects, we recommend using the customerGroupAssignments field due to greater flexibility.

This guide outlines how you can migrate from using the customerGroup field to using the customerGroupAssignments field in existing Projects.

Update Customers

You can use the customerGroup and customerGroupAssignments fields concurrently for existing projects. To add the customerGroupAssignments field do the following:

1. Query all Customers that have a value set for the customerGroup field.

   Examplebash

   curl -sH "Authorization: Bearer {access_token}" -X GET https://api.{region}.commercetools.com/{projectKey}/customers?where=customerGroup%20is%20defined
   

2. To add the customerGroup value to the customerGroupAssignments array, use the Add CustomerGroupAssignment update action for each Customer.

   Examplebash

   curl -sH "Authorization: Bearer {access_token}" -X POST \
     -d '{
       "version": "{version_number}",
       "actions": [
         {
           "action": "addCustomerGroupAssignment",
           "customerGroupAssignment": {
             "customerGroup": {
               "id": "{customer_group_id}",
               "typeId": "customer-group"
             }
           }
         }
       ]
     }' https://api.{region}.commercetools.com/{project_key}/customers/{customer_id}
   

Update Cart Discounts

For Cart Discounts, update the references from customerGroup to customerGroupAssignment by doing the following:

Update all customerGroup references in Cart Discounts to customerGroupAssignment by doing the following:

1. Query all Cart Discounts.

   Examplebash

   curl -sH "Authorization: Bearer {access_token}" -X GET \
     https://api.{region}.commercetools.com/{project_key}/cart-discounts
   

2. Review all your Cart Discounts to find ones that reference customerGroup in the cartPredicate field.

   Examplejson

   {
     "limit": 20,
     "offset": 0,
     "count": 1,
     "total": 1,
     "results": [
       {
         "id": "d32a9e93-561a-4fe3-a8c5-7678785460f7",
         "version": 1,
         "versionModifiedAt": "2024-06-13T07:52:46.340Z",
         "lastMessageSequenceNumber": 1,
         "createdAt": "2024-06-13T07:52:46.340Z",
         "lastModifiedAt": "2024-06-13T07:52:46.340Z",
         "lastModifiedBy": {
           "clientId": "BsuVMZkoV_N96VWGzDH4LquA",
           "isPlatformClient": false
         },
         "createdBy": {
           "clientId": "BsuVMZkoV_N96VWGzDH4LquA",
           "isPlatformClient": false
         },
         "value": {
           "type": "relative",
           "permyriad": 1000
         },
         "cartPredicate": "customer.customerGroup.key = \"test-group\"",
         "target": {
           "type": "shipping"
         },
         "name": {
           "en": "Old discount"
         },
         "description": {
           "en": "An old discount on the customerGroup field"
         },
         "stackingMode": "Stacking",
         "isActive": true,
         "requiresDiscountCode": false,
         "sortOrder": "0.9",
         "references": [],
         "stores": []
       }
     ]
   }
   

3. Use the Change Cart Predicate update action and replace all instances of customer.customerGroup with customer.customerGroupAssignments.customerGroup and replace = with contains.

   Examplebash

   curl -X POST \
     -d '{
       "version": "{version_number}"
       "actions": [
         {
           "action": "changeCartPredicate",
           "cartPredicate": "customer.customerGroupAssignments.customerGroup.key contains \"{customer-group-key}\""
         }
       ]
     }' \
     https://api.{region}.commercetools.com/{project_key}/cart-discounts/{cart_discount_id} \
     -H "Authorization: Bearer {access_token}" \
     -H "Content-Type: application/json"
   

Update other instances

Review any instances of the customerGroup field in your integration and replace them with customerGroupAssignments—for example, if you use the Customer object in an API Extension, you must update the customerGroup reference there too.