Menu

Customer Groups API Routes

Customers can be organized into groups. These groups are useful for segregation and marketing purposes.

For example, you can provide different prices for specific customers by creating a price list conditioned to their group.

These API routes allow admin users to manage groups and the customers in them.

GET /admin/customer-groups#

List Customer Groups

Retrieve a list of customer groups. The customer groups can be filtered by fields such as id. The customer groups can also be sorted or paginated.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.
offsetnumberOptional
The number of items to skip when retrieving a list.
limitnumberOptional
Limit the number of items returned in the list.
orderstringOptional
The field to sort the data by. By default, the sort order is ascending. To change the order to descending, prefix the field name with -.
qstringOptional
Search term to filter the customer group's searchable properties.
idstring | string[]Optional
Filter by a customer group's IDs.
namestring | string[]Optional
Filter by a customer group's name.
customersstring | string[] | objectOptional
Filter by the ID of a customer to retrieve its groups.
created_bystring | string[]Optional
Filter by an ID of a user to retrieve the customer groups they created.
created_atobjectOptional
Filter the customer group by its creation date. Accepts the filter operators.
updated_atobjectOptional
Filter the customer groups by their update date. Accepts the filter operators.
deleted_atobjectOptional
Filter the customer groups by their deletion date. Accepts the filter operators.
$andobject[]Optional
Join query parameters with an AND condition. Each object's content is the same type as the expected query parameters.
$orobject[]Optional
Join query parameters with an OR condition. Each object's content is the same type as the expected query parameters.
with_deletedbooleanOptional
Whether to include deleted records in the result.

Request examples

Responses

200 OK

limitnumber
The maximum number of items retrieved.
offsetnumber
The number of items skipped before retrieving the returned items.
countnumber
The total number of items
customer_groupsobject[]
The list of customer groups.

400, 401, 404, 409, 422, 500: an error response is returned.

POST /admin/customer-groups#

Create Customer Group

Create a customer group.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.

Request body (application/json)

namestring
The customer group's name.
metadataobjectOptional
The customer group's metadata, used to store custom key-value pairs. Learn more in the Manage Metadata section.

Request examples

Responses

200 OK

customer_groupobject
The customer group's details.

400, 401, 404, 409, 422, 500: an error response is returned.

GET /admin/customer-groups/{id}#

Get a Customer Group

Retrieve a customer group by its ID. You can expand the customer group's relations or select the fields that should be returned.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The customer group's ID.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.

Request examples

Responses

200 OK

customer_groupobject
The customer group's details.

400, 401, 404, 409, 422, 500: an error response is returned.

POST /admin/customer-groups/{id}#

Update a Customer Group

Update a customer group's details.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The customer group's ID.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.

Request body (application/json)

namestringOptional
The customer group's name.
metadataobjectOptional
The customer group's metadata, can hold custom key-value pairs. Learn more in the Manage Metadata section.

Request examples

Responses

200 OK

customer_groupobject
The customer group's details.

400, 401, 404, 409, 422, 500: an error response is returned.

DELETE /admin/customer-groups/{id}#

Delete a Customer Group

Delete a customer group. Customers in the group aren't deleted.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The customer group's ID.

Request examples

Responses

200 OK

idstring
The customer group's ID.
objectstring
The customer group's object.
deletedboolean
The customer group's deleted.

400, 401, 404, 409, 422, 500: an error response is returned.

POST /admin/customer-groups/{id}/customers#

Manage Customers of a Customer Group

Manage the customers of a group to add or remove them from the group.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The customer group's ID.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.

Request body (application/json)

addstring[]Optional
The IDs of an entity to add to the other.
removestring[]Optional
The IDs of an entity to remove from the other.

Request examples

Responses

200 OK

customer_groupobject
The customer group's details.

400, 401, 404, 409, 422, 500: an error response is returned.

Found a problem with this page?Report Issue
Edited Nov 14·Edit this page