# Migrate to multiple Customer Groups

Learn how to migrate existing Projects from using a single Customer Group per Customer to using multiple Customer Groups.

The [Customer](https://docs.commercetools.com/urn?urn=ctp%3Aapi%3Atype%3ACustomer) resource supports two fields for assigning Customers to Customer Groups:

- `customerGroup`: allows assigning one Customer Group to a Customer
- `customerGroupAssignments`: allows assigning up to 500 Customer Groups to a Customer

While both fields can be used in existing Projects, the `customerGroupAssignments` field offers greater flexibility, even in complex pricing scenarios. For more information about the price selection logic when using multiple Customer Groups, see [Fallback logic for multiple Customer Groups](https://docs.commercetools.com/api/pricing-and-discounts-overview.md#fallback-logic-for-multiple-customer-groups).

We recommend only using the `customerGroupAssignments` field in new projects.

To migrate from using the `customerGroup` field to using `customerGroupAssignments` in existing projects, follow these steps:

1. [Update Customers](https://docs.commercetools.com/tutorials/migration-guides/multiple-customer-groups.md#update-customers)
2. [Update Cart Discounts](https://docs.commercetools.com/tutorials/migration-guides/multiple-customer-groups.md#update-cart-discounts)
3. [Update other instances](https://docs.commercetools.com/tutorials/migration-guides/multiple-customer-groups.md#update-other-instances)
4. [Update Customers](https://docs.commercetools.com/tutorials/migration-guides/multiple-customer-groups.md#update-customers)

## Update Customers

Add the `customerGroupAssignments` field to the Customer resource.

1. [Query Customers](https://docs.commercetools.com/urn?urn=ctp%3Aapi%3Aendpoint%3A%2F%7BprojectKey%7D%2Fcustomers%3AGET) that have a value set for the `customerGroup` field.

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

2. Add the `customerGroup` value to the `customerGroupAssignments` array, using the [Add CustomerGroupAssignment](https://docs.commercetools.com/api/projects/customers.md#add-customergroupassignment) update action for each Customer.

   ```bash title="Example"
   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

Update references to `customerGroup` in Cart Discount predicates to `customerGroupAssignment`.

1. [Query CartDiscounts](https://docs.commercetools.com/urn?urn=ctp%3Aapi%3Aendpoint%3A%2F%7BprojectKey%7D%2Fcart-discounts%3AGET).

   ```bash title="Example"
   curl -sH "Authorization: Bearer {access_token}" -X GET 
     https://api.{region}.commercetools.com/{project_key}/cart-discounts
   ```

2. Review the Cart Discounts to find references to `customerGroup` in the `cartPredicate` field.

   ```json highlightLines="26" title="Example"
   {
     "limit": 20,
     "offset": 0,
     "count": 1,
     "total": 1,
     "results": [
       {
         "id": "d32a9e93-561a-4fe3-a8c5-7678785460f7",
         "version": 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](https://docs.commercetools.com/api/projects/cartDiscounts.md#change-cart-predicate) update action and replace all instances of `customer.customerGroup` with `customer.customerGroupAssignments.customerGroup`, and replace `=` with `contains`.

   ```bash title="Example"
   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](https://docs.commercetools.com/urn?urn=ctp%3Aapi%3Atype%3ACustomer) object in an [API Extension](https://docs.commercetools.com/api/projects/api-extensions.md), update the `customerGroup` reference there too.

## Update Customers

Remove the `customerGroup` value from the Customers resource using the [Set Customer Group](https://docs.commercetools.com/api/projects/customers.md#set-customergroup) update action (with an empty value), after migrating all relevant data to `customerGroupAssignments` and validating if your pricing and discount logic work as intended.

```bash title="Example"
curl -sH "Authorization: Bearer {access_token}" -X POST 
  -d '{
    "version": "{version_number}",
    "actions": [
      {
        "action": "setCustomerGroup"
      }
    ]
  }' https://api.{region}.commercetools.com/{project_key}/customers/{customer_id}
```

The `customerGroup` field is not deprecated and will continue to be supported; using the `customerGroupAssignments` exclusively is the recommended best practice as it ensures:

- consistent use of the `customerGroupAssignments` field for pricing and discount logic
- removal of ambiguity between `customerGroup` and `customerGroupAssignments`
- full access to the flexibility of assigning multiple Customer Groups

## Related pages

- [Section overview page](https://docs.commercetools.com/tutorials.md)
- [Next page: Migrate checkout](https://docs.commercetools.com/tutorials/strangler-pattern.md)