Documentation

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 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.
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
  2. Update Cart Discounts
  3. Update other instances
  4. Update Customers

Update Customers

Add the customerGroupAssignments field to the Customer resource.
  1. Query 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. Add the customerGroup value to the customerGroupAssignments array, using 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

Update references to customerGroup in Cart Discount predicates to customerGroupAssignment.
  1. Query CartDiscounts.
    Examplebash
    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.
    Examplejson
    {
  "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 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, update the customerGroup reference there too.

Update Customers

Remove the customerGroup value from the Customers resource using the Set Customer Group update action (with an empty value), after migrating all relevant data to customerGroupAssignments and validating if your pricing and discount logic work as intended.
Examplebash
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