Backend API: Manage customer groups

This document describes how to manage customer groups using the Backend API. You can use these endpoints to build Back Office extensions, CRM and marketing automation integrations, and segmentation pipelines.

A customer group is a named segment of customers. Discounts and other shop rules target a group, so moving a customer in or out of one changes what that customer sees. A customer can belong to any number of groups at the same time.

Customer groups are addressed by uuid. The internal database identifier is never exposed. The UUID is derived from the group id, so it is stable for the lifetime of the group — renaming the group does not change it.

The group itself and its members are managed through two resources: /customer-groups carries the name and description, and /customer-groups/{uuid}/customers carries the members.

Installation

These endpoints are provided by API Platform. To install and enable it, see Enable API Platform.

docker/sdk console uuid:generate CustomerGroup spy_customer_group

Retrieve customer groups

To retrieve a paginated collection of customer groups, send the request:

GET /customer-groups

Request

The free-text search and the name filter are combined with AND, so each one you add narrows the result further. A name that no group uses returns an empty collection rather than an error.

Sorting by a field that is not on the list returns 400 with the error code 1203, and the error message names the supported fields. When you pass several fields, the second one decides the order only where the first one ties.

The members of a group are neither part of this response nor available as an include. To read them, see Retrieve the customers of a customer group.

Response

{
    "data": [
        {
            "type": "customer-groups",
            "id": "4b1e6a02-9f37-5c48-b6d1-2e8a70c9f4a5",
            "attributes": {
                "uuid": "4b1e6a02-9f37-5c48-b6d1-2e8a70c9f4a5",
                "name": "Wholesale partners",
                "description": "Customers eligible for wholesale pricing tiers.",
                "createdAt": "2026-09-10T08:15:00+00:00"
            },
            "links": {
                "self": "https://glue-backend.mysprykershop.com/customer-groups/4b1e6a02-9f37-5c48-b6d1-2e8a70c9f4a5"
            }
        },
        {
            "type": "customer-groups",
            "id": "7d3c5f81-6a24-5e93-8c07-1b2f4a6d9e30",
            "attributes": {
                "uuid": "7d3c5f81-6a24-5e93-8c07-1b2f4a6d9e30",
                "name": "Tier one",
                "description": null,
                "createdAt": "2026-09-12T11:42:31+00:00"
            },
            "links": {
                "self": "https://glue-backend.mysprykershop.com/customer-groups/7d3c5f81-6a24-5e93-8c07-1b2f4a6d9e30"
            }
        }
    ],
    "meta": {
        "pagination": {
            "numFound": 12,
            "currentPage": 1,
            "maxPage": 2,
            "currentItemsPerPage": 10
        }
    },
    "links": {
        "self": "https://glue-backend.mysprykershop.com/customer-groups",
        "first": "https://glue-backend.mysprykershop.com/customer-groups?page[limit]=10&page[offset]=0",
        "last": "https://glue-backend.mysprykershop.com/customer-groups?page[limit]=10&page[offset]=10",
        "next": "https://glue-backend.mysprykershop.com/customer-groups?page[limit]=10&page[offset]=10"
    }
}

A collection response carries its pagination summary in the top-level meta.pagination object:

The top-level links object carries the first and last links, plus prev and next when those pages exist. Each link repeats the query parameters of the request and rewrites the window as page[limit] and page[offset], so you can follow it as it is.

Retrieve a customer group

To retrieve a single customer group, send the request:

GET /customer-groups/{{customer_group_uuid}}

Request

Request sample: GET https://glue-backend.mysprykershop.com/customer-groups/4b1e6a02-9f37-5c48-b6d1-2e8a70c9f4a5

Response

The response contains the same attributes as Retrieve customer groups, without the meta.pagination object.

If no group matches the UUID, the endpoint returns 404 with the error code 1222.

Create a customer group

To create a customer group, send the request:

POST /customer-groups

Request

You can create an empty group and fill it later, or assign its members in the same request.

Request sample: create an empty customer group

POST https://glue-backend.mysprykershop.com/customer-groups

{
    "data": {
        "type": "customer-groups",
        "attributes": {
            "name": "Wholesale partners",
            "description": "Customers eligible for wholesale pricing tiers."
        }
    }
}

Request sample: create a customer group with members

POST https://glue-backend.mysprykershop.com/customer-groups

{
    "data": {
        "type": "customer-groups",
        "attributes": {
            "name": "Wholesale partners",
            "description": "Customers eligible for wholesale pricing tiers.",
            "customerReferences": [
                "DE--1",
                "DE--2"
            ]
        }
    }
}

Names are compared without regard to case: with a group named Wholesale partners already present, WHOLESALE PARTNERS is rejected with 422 and the error code 1223.

Every customer reference must belong to an existing customer. If any of them is unknown, the endpoint rejects the whole request and creates no group. The response returns 422 with the error code 1224 and one errors[] entry per unknown reference, so a single request tells you every reference you need to correct.

The customer accounts themselves are neither read back nor modified, and no mail is sent.

Response

A successful request returns the 201 Created status code.

Response sample:

{
    "data": {
        "type": "customer-groups",
        "id": "4b1e6a02-9f37-5c48-b6d1-2e8a70c9f4a5",
        "attributes": {
            "uuid": "4b1e6a02-9f37-5c48-b6d1-2e8a70c9f4a5",
            "name": "Wholesale partners",
            "description": "Customers eligible for wholesale pricing tiers.",
            "createdAt": "2026-09-24T09:05:12+00:00"
        },
        "links": {
            "self": "https://glue-backend.mysprykershop.com/customer-groups/4b1e6a02-9f37-5c48-b6d1-2e8a70c9f4a5"
        }
    }
}

customerReferences is write-only and is never returned. To confirm the assignment, see Retrieve the customers of a customer group.

Edit a customer group

To update a customer group, send the request:

PATCH /customer-groups/{{customer_group_uuid}}

Request

Request sample: PATCH https://glue-backend.mysprykershop.com/customer-groups/4b1e6a02-9f37-5c48-b6d1-2e8a70c9f4a5

{
    "data": {
        "type": "customer-groups",
        "id": "4b1e6a02-9f37-5c48-b6d1-2e8a70c9f4a5",
        "attributes": {
            "name": "Wholesale partners EU",
            "description": "Customers eligible for wholesale pricing tiers in the EU."
        }
    }
}

The endpoint applies only the attributes present in the payload; every attribute you omit keeps its stored value.

Renaming a group does not change its UUID, so links and integrations that address the group keep working. Sending the group its own current name succeeds and changes nothing. Sending a name another group already uses, in any casing, returns 422 with the error code 1223.

Response

The response contains the updated customer group, with the same attributes as Retrieve a customer group.

Delete a customer group

To delete a customer group, send the request:

DELETE /customer-groups/{{customer_group_uuid}}

Request

Request sample: DELETE https://glue-backend.mysprykershop.com/customer-groups/4b1e6a02-9f37-5c48-b6d1-2e8a70c9f4a5

Response

A successful request returns the 204 No Content status code with an empty body.

The assignments of the group go with it. The customers themselves are kept, along with every other group they belong to.

Retrieve the customers of a customer group

To retrieve a paginated collection of the customers assigned to a group, send the request:

GET /customer-groups/{{customer_group_uuid}}/customers

Request

The collection lists only the members of the group in the URL. A customer who belongs to several groups appears in each of them.

Sorting by a field that is not on the list returns 400 with the error code 1203, and the error message names the supported fields.

Response

{
    "data": [
        {
            "type": "customer-group-customers",
            "id": "DE--1",
            "attributes": {
                "customerReference": "DE--1",
                "email": "[email protected]",
                "firstName": "Spencor",
                "lastName": "Hopkins"
            }
        },
        {
            "type": "customer-group-customers",
            "id": "DE--2",
            "attributes": {
                "customerReference": "DE--2",
                "email": "[email protected]",
                "firstName": "Jane",
                "lastName": "Smith"
            }
        }
    ],
    "meta": {
        "pagination": {
            "numFound": 2,
            "currentPage": 1,
            "maxPage": 1,
            "currentItemsPerPage": 10
        }
    },
    "links": {
        "self": "https://glue-backend.mysprykershop.com/customer-groups/4b1e6a02-9f37-5c48-b6d1-2e8a70c9f4a5/customers",
        "first": "https://glue-backend.mysprykershop.com/customer-groups/4b1e6a02-9f37-5c48-b6d1-2e8a70c9f4a5/customers?page[limit]=10&page[offset]=0",
        "last": "https://glue-backend.mysprykershop.com/customer-groups/4b1e6a02-9f37-5c48-b6d1-2e8a70c9f4a5/customers?page[limit]=10&page[offset]=0"
    }
}

All four attributes are read-only. To change customer data, see Backend API: Manage customers.

A collection response carries its pagination summary in the top-level meta.pagination object:

The top-level links object carries the first and last links, plus prev and next when those pages exist. Each link repeats the query parameters of the request and rewrites the window as page[limit] and page[offset], so you can follow it as it is.

If no group matches the UUID, the endpoint returns 404 with the error code 1222.

Add customers to a customer group

To add customers to a group without removing the members it already has, send the request:

POST /customer-groups/{{customer_group_uuid}}/customers

Request

Request sample: POST https://glue-backend.mysprykershop.com/customer-groups/4b1e6a02-9f37-5c48-b6d1-2e8a70c9f4a5/customers

{
    "data": {
        "type": "customer-group-customers",
        "attributes": {
            "customerReferences": [
                "DE--1",
                "DE--2"
            ]
        }
    }
}

The members the group already has stay as they are. References that are already members are skipped, so sending the same request twice is safe and changes nothing the second time.

The operation is all-or-nothing: if any reference is unknown, nothing is added, and the response returns 422 with the error code 1224 and one errors[] entry per unknown reference.

The customer accounts themselves are neither read back nor modified, and no mail is sent.

Response

A successful request returns the 204 No Content status code with an empty body. To read the resulting membership, see Retrieve the customers of a customer group.

Replace the customers of a customer group

To set the complete list of members of a group in one call, send the request:

PATCH /customer-groups/{{customer_group_uuid}}/customers

Request

Request sample: PATCH https://glue-backend.mysprykershop.com/customer-groups/4b1e6a02-9f37-5c48-b6d1-2e8a70c9f4a5/customers

{
    "data": {
        "type": "customer-group-customers",
        "attributes": {
            "customerReferences": [
                "DE--1",
                "DE--3"
            ]
        }
    }
}

The references you send become the complete new set of members, so include every customer the group is to keep. Customers missing from the list are removed from the group; their accounts, and their assignments to other groups, stay untouched.

An empty array removes every member and keeps the group itself, which is how you clear a group without deleting it.

The operation is all-or-nothing: if any reference is unknown or the list contains duplicates, the membership stays exactly as it was, and the response returns 422 with the error code 1224 and one errors[] entry per unknown reference. Sending the same list twice leaves the same members.

Response

A successful request returns the 204 No Content status code with an empty body. To read the resulting membership, see Retrieve the customers of a customer group.

Remove a customer from a customer group

To remove one customer from a group, send the request:

DELETE /customer-groups/{{customer_group_uuid}}/customers/{{customer_reference}}

Request

Request sample: DELETE https://glue-backend.mysprykershop.com/customer-groups/4b1e6a02-9f37-5c48-b6d1-2e8a70c9f4a5/customers/DE--1

Response

A successful request returns the 204 No Content status code with an empty body.

The customer account is kept, and so is every other group the customer belongs to.

If no group matches the UUID, the endpoint returns 404 with the error code 1222. If the group exists but the customer is not one of its members, the endpoint returns 404 with the error code 1225.

Other management options

• Backend API: Manage customers
• Backend API: Manage customer addresses
• Backend API: Manage customer notes
• Backend API: Manage customer access
• Manage customer groups in the Back Office
• Customer groups overview

Possible errors

To view generic errors, see API errors and troubleshooting.