Backend API: Manage companies and business units of customer groups

This document describes how to manage the company and business unit memberships of customer groups using the Backend API. You can use these endpoints to keep the membership of customer groups in sync from integrations, such as ERP and CRM systems or partner administration tools.

Besides customers, a customer group can have companies and business units as members. A company or a business unit can belong to any number of groups at the same time. These are the same memberships that you manage on the Companies and Business Units tabs of a customer group in the Back Office.

Company and business unit memberships are stored and managed with the group, and they do not affect discounts, prices, catalogs, or the Storefront. Discounts and other rules that target a customer group evaluate only the customers of the group.

The memberships are managed through two resources: /customer-groups/{uuid}/companies carries the member companies, and /customer-groups/{uuid}/company-business-units carries the member business units. Both address the customer group by its uuid. To manage the group itself and its customers, see Backend API: Manage customer groups.

Installation

These endpoints are provided by the B2B Customer Groups feature. To install the feature, see Install the B2B Customer Groups feature.

The endpoints are implemented using API Platform. To install and enable it, see Enable API Platform.

If your project had customer groups before it installed the customer group UUIDs, generate the missing UUIDs as described in Backend API: Manage customer groups.

How company and business unit memberships relate

A customer group keeps its companies and its business units as two independent sets of members. Changing one set never changes the other:

• Adding a company does not add its business units. Adding a business unit does not add its company, its parent or child business units, or its company users.
• Removing a company keeps the business units of that company that belong to the group.
• Removing the last business unit of a company keeps the membership of the company.
• Replacing the companies of a group leaves its business units as they are, and replacing the business units leaves its companies as they are.

As a result, a group can have business units of a company without having the company itself, and it can have business units of several companies.

The endpoints change only memberships. The companies, business units, and company users themselves are never modified, and the customers of the group stay as they are.

A membership is removed automatically when its customer group, company, or business unit is deleted.

Retrieve the companies of a customer group

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

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

Request

Without sort, the companies are listed in the order in which they were created. Companies with the same name keep a fixed order, so paging through the collection never repeats or skips a company.

Sorting by any other field returns 400 with the error code 1203, and the error message names the supported field. The collection supports no filters: a filter parameter returns 400 with the error code 1215.

Response

{
    "links": {
        "self": "https://glue-backend.mysprykershop.com/customer-groups/d01a3f13-7687-50d0-8aac-2cac53ff7a61/companies?sort=name",
        "first": "https://glue-backend.mysprykershop.com/customer-groups/d01a3f13-7687-50d0-8aac-2cac53ff7a61/companies?sort=name&page[limit]=2&page[offset]=0",
        "last": "https://glue-backend.mysprykershop.com/customer-groups/d01a3f13-7687-50d0-8aac-2cac53ff7a61/companies?sort=name&page[limit]=2&page[offset]=8",
        "next": "https://glue-backend.mysprykershop.com/customer-groups/d01a3f13-7687-50d0-8aac-2cac53ff7a61/companies?sort=name&page[limit]=2&page[offset]=2"
    },
    "meta": {
        "pagination": {
            "numFound": 9,
            "currentPage": 1,
            "maxPage": 5,
            "currentItemsPerPage": 2
        }
    },
    "data": [
        {
            "id": "59b6c025-cc00-54ca-b101-191391adf2af",
            "type": "customer-group-companies",
            "attributes": {
                "companyUuid": "59b6c025-cc00-54ca-b101-191391adf2af",
                "companyName": "BoB-Hotel Jim"
            }
        },
        {
            "id": "94f34a90-4217-5165-8a92-1332e4dd011b",
            "type": "customer-group-companies",
            "attributes": {
                "companyUuid": "94f34a90-4217-5165-8a92-1332e4dd011b",
                "companyName": "BoB-Hotel Ku'damm"
            }
        }
    ]
}

Both attributes are read-only. Without include, a membership has no relationships. To change company data, see Backend API: Manage companies.

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 companies to a customer group

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

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

Request

Request sample: POST https://glue-backend.mysprykershop.com/customer-groups/d01a3f13-7687-50d0-8aac-2cac53ff7a61/companies

{
    "data": {
        "type": "customer-group-companies",
        "attributes": {
            "companyUuids": [
                "59b6c025-cc00-54ca-b101-191391adf2af",
                "88efe8fb-98bd-5423-a041-a8f866c0f913"
            ]
        }
    }
}

The companies the group already has stay as they are. Companies 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 UUID matches no company, nothing is added, and the response returns 422 with the error code 1236 and one errors[] entry per unknown UUID.

Adding a company does not add its business units. To add them too, see Add business units to a customer group.

Response

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

Replace the companies of a customer group

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

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

Request

Request sample: PATCH https://glue-backend.mysprykershop.com/customer-groups/d01a3f13-7687-50d0-8aac-2cac53ff7a61/companies

{
    "data": {
        "type": "customer-group-companies",
        "attributes": {
            "companyUuids": [
                "59b6c025-cc00-54ca-b101-191391adf2af",
                "94f34a90-4217-5165-8a92-1332e4dd011b"
            ]
        }
    }
}

The UUIDs you send become the complete new set of member companies, so include every company the group is to keep. Companies missing from the list are removed from the group; the companies themselves, and their memberships in other groups, stay untouched. The business units of the group stay as they are.

An empty array removes every company from the group in one request, whatever the number of companies, and keeps the group itself.

The operation is all-or-nothing: if any UUID matches no company, the membership stays exactly as it was, and the response returns 422 with the error code 1236 and one errors[] entry per unknown UUID. Sending the same list twice leaves the same companies.

Response

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

Remove a company from a customer group

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

DELETE /customer-groups/{{customer_group_uuid}}/companies/{{company_uuid}}

Request

Request sample: DELETE https://glue-backend.mysprykershop.com/customer-groups/d01a3f13-7687-50d0-8aac-2cac53ff7a61/companies/88efe8fb-98bd-5423-a041-a8f866c0f913

Response

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

The company is kept, and so are its memberships in other groups. The business units of the group, including the business units of the removed company, stay as they are.

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

Retrieve the business units of a customer group

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

GET /customer-groups/{{customer_group_uuid}}/company-business-units

Request

Without sort, the business units are listed in the order in which they were created. Business units with the same name keep a fixed order, so paging through the collection never repeats or skips a business unit.

Sorting by any other field returns 400 with the error code 1203, and the error message names the supported field.

companyUuid is the only filterable property. A filter on any other property, or a companyUuid filter with more than one value, returns 400 with the error code 1215. A filter key that is not in the filter[customer-group-company-business-units.<property>] form returns 400 with the error code 011.

Response

{
    "links": {
        "self": "https://glue-backend.mysprykershop.com/customer-groups/d01a3f13-7687-50d0-8aac-2cac53ff7a61/company-business-units?filter%5Bcustomer-group-company-business-units.companyUuid%5D=62de4ab6-b768-5c21-8835-455d9f341625&sort=name",
        "first": "https://glue-backend.mysprykershop.com/customer-groups/d01a3f13-7687-50d0-8aac-2cac53ff7a61/company-business-units?filter[customer-group-company-business-units.companyUuid]=62de4ab6-b768-5c21-8835-455d9f341625&sort=name&page[limit]=2&page[offset]=0",
        "last": "https://glue-backend.mysprykershop.com/customer-groups/d01a3f13-7687-50d0-8aac-2cac53ff7a61/company-business-units?filter[customer-group-company-business-units.companyUuid]=62de4ab6-b768-5c21-8835-455d9f341625&sort=name&page[limit]=2&page[offset]=4",
        "next": "https://glue-backend.mysprykershop.com/customer-groups/d01a3f13-7687-50d0-8aac-2cac53ff7a61/company-business-units?filter[customer-group-company-business-units.companyUuid]=62de4ab6-b768-5c21-8835-455d9f341625&sort=name&page[limit]=2&page[offset]=2"
    },
    "meta": {
        "pagination": {
            "numFound": 5,
            "currentPage": 1,
            "maxPage": 3,
            "currentItemsPerPage": 2
        }
    },
    "data": [
        {
            "id": "ff1c18c9-fb5d-514d-9358-79887ed6d5c6",
            "type": "customer-group-company-business-units",
            "attributes": {
                "companyBusinessUnitUuid": "ff1c18c9-fb5d-514d-9358-79887ed6d5c6",
                "companyBusinessUnitName": "Acme Corporation",
                "companyUuid": "62de4ab6-b768-5c21-8835-455d9f341625",
                "companyName": "Acme Corporation"
            }
        },
        {
            "id": "d8943c86-4481-5c2a-b5f6-28c8dbdf1a23",
            "type": "customer-group-company-business-units",
            "attributes": {
                "companyBusinessUnitUuid": "d8943c86-4481-5c2a-b5f6-28c8dbdf1a23",
                "companyBusinessUnitName": "Acme Corporation Barcelona",
                "companyUuid": "62de4ab6-b768-5c21-8835-455d9f341625",
                "companyName": "Acme Corporation"
            }
        }
    ]
}

All four attributes are read-only. Without include, a membership has no relationships. To change business unit data, see Backend API: Manage company business units.

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 business units to a customer group

To add business units to a group without removing the business units it already has, send the request:

POST /customer-groups/{{customer_group_uuid}}/company-business-units

Request

Request sample: POST https://glue-backend.mysprykershop.com/customer-groups/d01a3f13-7687-50d0-8aac-2cac53ff7a61/company-business-units

{
    "data": {
        "type": "customer-group-company-business-units",
        "attributes": {
            "companyBusinessUnitUuids": [
                "073389b6-9ee8-5c90-a8a7-a830aab6a330",
                "5860fdd0-21fc-5389-87c9-5f1507d1ef3e"
            ]
        }
    }
}

The business units the group already has stay as they are. Business units 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 UUID matches no business unit, nothing is added, and the response returns 422 with the error code 1238 and one errors[] entry per unknown UUID.

Adding a business unit does not add its company, its parent or child business units, or its company users. A group can have business units of several companies.

Response

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

Replace the business units of a customer group

To set the complete list of member business units of a group in one call, send the request:

PATCH /customer-groups/{{customer_group_uuid}}/company-business-units

Request

Request sample: PATCH https://glue-backend.mysprykershop.com/customer-groups/d01a3f13-7687-50d0-8aac-2cac53ff7a61/company-business-units

{
    "data": {
        "type": "customer-group-company-business-units",
        "attributes": {
            "companyBusinessUnitUuids": [
                "073389b6-9ee8-5c90-a8a7-a830aab6a330",
                "d8943c86-4481-5c2a-b5f6-28c8dbdf1a23"
            ]
        }
    }
}

The UUIDs you send become the complete new set of member business units, so include every business unit the group is to keep. Business units missing from the list are removed from the group; the business units themselves, and their memberships in other groups, stay untouched. The companies of the group stay as they are, including the companies whose last business unit you remove.

An empty array removes every business unit from the group in one request, whatever the number of business units, and keeps the group itself.

The operation is all-or-nothing: if any UUID matches no business unit, the membership stays exactly as it was, and the response returns 422 with the error code 1238 and one errors[] entry per unknown UUID. Sending the same list twice leaves the same business units.

As with companies, companyBusinessUnitUuids is required, and a body without it is rejected with 422. The list is capped at 1000 entries, so to change a group that keeps more than 1000 business units, use Add business units to a customer group and Remove a business unit from a customer group instead.

Response

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

Remove a business unit from a customer group

To remove one business unit from a group, send the request:

DELETE /customer-groups/{{customer_group_uuid}}/company-business-units/{{company_business_unit_uuid}}

Request

Request sample: DELETE https://glue-backend.mysprykershop.com/customer-groups/d01a3f13-7687-50d0-8aac-2cac53ff7a61/company-business-units/073389b6-9ee8-5c90-a8a7-a830aab6a330

Response

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

The business unit is kept, and so are its memberships in other groups. The companies of the group stay as they are, including the company of the removed business unit.

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

Other management options

• Backend API: Manage customer groups
• Backend API: Manage companies
• Backend API: Manage company business units
• Manage customer groups in the Back Office
• Customer groups overview

Possible errors

To view generic errors, see API errors and troubleshooting.