Commerce Layer is proud to be an official sponsor the JAMstack Conf in London — 09-10 July, 2019 🎉 Don't miss out!

API REFERENCE

Customer Groups

A customer group is a resource that can be used to organize customers into groups. When you associate a price list to a customer group, all the customers belonging to that group get its price list, overridining the one defined at market level. You can use customer groups to manage B2B customers, B2C loyalty programs, and more.

The customer group object

A Customer group object is returned as part of the response body of each successful create, list, retrieve or update API call. The following table contains the list of all its fields along with their type, description and example values.

Object fields:
name
string
The customer group's internal name
Example:
id
integer
Unique identifier for the resource.
Example:
1234
created_at
datetime
Time at which the resource was created.
Example:
2018-01-01T12:00:00.000Z
updated_at
datetime
Time at which the resource was last updated.
Example:
2018-01-01T12:00:00.000Z
reference
string
A string that you can use to add your own identifier to the resource. This can be useful for intergrating the resource to an external system, like an ERP, a marketing tool or a CRM.
Example:
ANYREFEFERNCE
metadata
object
Set of key-value pairs that you can attach to the resource. This can be useful for storing additional information about the resource in a structured format.
Example:
{"foo":"bar"}
relationship (N:1)
The associated price list.
relationship (1:N)
The customers belonging to this group.

Create a customer group

To create a new customer group, send a POST request to the /api/customer_groups endpoint, passing the resource arguments in the request body. The following table contains the list of all the possible arguments, along with their type, description and examples values. All the arguments marked as required must be present in the request.

Arguments:
name
required
The customer group's internal name
Example:
reference
optional
A string that you can use to add your own identifier to the resource. This can be useful for intergrating the resource to an external system, like an ERP, a marketing tool or a CRM.
Example:
ANYREFEFERNCE
metadata
optional
Set of key-value pairs that you can attach to the resource. This can be useful for storing additional information about the resource in a structured format.
Example:
{"foo":"bar"}
optional
The associated price list.
Example request:
POST /api/customer_groups HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "data": {
    "type": "customer_groups",
    "attributes": {
      "name": null
    }
  }
}
Example response:
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json

{
  "data": {
    "id": "1234",
    "type": "customer_groups",
    "links": {
      "self": "https://your-brand.commercelayer.io/api/customer_groups/1234"
    },
    "attributes": {
      "name": null,
      "id": "1234",
      "created_at": "2018-01-01T12:00:00.000Z",
      "updated_at": "2018-01-01T12:00:00.000Z",
      "reference": "ANYREFEFERNCE",
      "metadata": {
        "foo": "bar"
      }
    },
    "relationships": {
      "price_list": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/customer_groups/1234/relationships/price_list",
          "related": "https://your-brand.commercelayer.io/api/customer_groups/1234/price_list"
        }
      },
      "customers": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/customer_groups/1234/relationships/customers",
          "related": "https://your-brand.commercelayer.io/api/customer_groups/1234/customers"
        }
      }
    },
    "meta": {
      "mode": "test"
    }
  }
}

List all customer groups

To fetch a collection of customer groups, send a GET request to the /api/customer_groups endpoint.

Example request:
GET /api/customer_groups HTTP/1.1
Accept: application/vnd.api+json
Example response:
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": [
    {
      "id": "1234",
      "type": "customer_groups",
      "links": {
        "self": "https://your-brand.commercelayer.io/api/customer_groups/1234"
      },
      "attributes": {
        "name": null,
        "id": "1234",
        "created_at": "2018-01-01T12:00:00.000Z",
        "updated_at": "2018-01-01T12:00:00.000Z",
        "reference": "ANYREFEFERNCE",
        "metadata": {
          "foo": "bar"
        }
      },
      "relationships": {
        "price_list": {
          "links": {
            "self": "https://your-brand.commercelayer.io/api/customer_groups/1234/relationships/price_list",
            "related": "https://your-brand.commercelayer.io/api/customer_groups/1234/price_list"
          }
        },
        "customers": {
          "links": {
            "self": "https://your-brand.commercelayer.io/api/customer_groups/1234/relationships/customers",
            "related": "https://your-brand.commercelayer.io/api/customer_groups/1234/customers"
          }
        }
      },
      "meta": {
        "mode": "test"
      }
    },
    {
      "other": "... 24 customer_groups (first page)"
    }
  ],
  "meta": {
    "record_count": 125,
    "page_count": 5
  },
  "links": {
    "first": "/api/customer_groups?page[number]=1&page[size]=25",
    "prev": "/api/customer_groups?page[number]=2&page[size]=25",
    "next": "/api/customer_groups?page[number]=4&page[size]=25",
    "last": "/api/customer_groups?page[number]=5&page[size]=25"
  }
}
Sortable attributes
name id created_at updated_at reference

Retrieve a customer group

To fetch a single customer group, send a GET request to the /api/customer_groups/{{id}} endpoint, where {{id}} is the id of the resource that you want to retrieve.

Example request:
GET /api/customer_groups/1234 HTTP/1.1
Accept: application/vnd.api+json
Example response:
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": {
    "id": "1234",
    "type": "customer_groups",
    "links": {
      "self": "https://your-brand.commercelayer.io/api/customer_groups/1234"
    },
    "attributes": {
      "name": null,
      "id": "1234",
      "created_at": "2018-01-01T12:00:00.000Z",
      "updated_at": "2018-01-01T12:00:00.000Z",
      "reference": "ANYREFEFERNCE",
      "metadata": {
        "foo": "bar"
      }
    },
    "relationships": {
      "price_list": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/customer_groups/1234/relationships/price_list",
          "related": "https://your-brand.commercelayer.io/api/customer_groups/1234/price_list"
        }
      },
      "customers": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/customer_groups/1234/relationships/customers",
          "related": "https://your-brand.commercelayer.io/api/customer_groups/1234/customers"
        }
      }
    },
    "meta": {
      "mode": "test"
    }
  }
}

Update a customer group

To update an existing customer group, send a PATCH request to the /api/customer_groups/{{id}} endpoint, where {{id}} is the id of the resource that you want to update. The following table contains the list of all the possible arguments that you can pass with the request body, along with their type, description and examples values. Please note that all arguments are optional.

Arguments:
name
optional
The customer group's internal name
Example:
reference
optional
A string that you can use to add your own identifier to the resource. This can be useful for intergrating the resource to an external system, like an ERP, a marketing tool or a CRM.
Example:
ANYREFEFERNCE
metadata
optional
Set of key-value pairs that you can attach to the resource. This can be useful for storing additional information about the resource in a structured format.
Example:
{"foo":"bar"}
optional
The associated price list.
Example request:
PATCH /api/customer_groups/1234 HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "data": {
    "type": "customer_groups",
    "id": 1234,
    "attributes": {
      "name": null
    },
    "relationships": {
    }
  }
}
Example response:
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json

{
  "data": {
    "id": "1234",
    "type": "customer_groups",
    "links": {
      "self": "https://your-brand.commercelayer.io/api/customer_groups/1234"
    },
    "attributes": {
      "name": null,
      "id": "1234",
      "created_at": "2018-01-01T12:00:00.000Z",
      "updated_at": "2018-01-01T12:00:00.000Z",
      "reference": "ANYREFEFERNCE",
      "metadata": {
        "foo": "bar"
      }
    },
    "relationships": {
      "price_list": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/customer_groups/1234/relationships/price_list",
          "related": "https://your-brand.commercelayer.io/api/customer_groups/1234/price_list"
        }
      },
      "customers": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/customer_groups/1234/relationships/customers",
          "related": "https://your-brand.commercelayer.io/api/customer_groups/1234/customers"
        }
      }
    },
    "meta": {
      "mode": "test"
    }
  }
}

Delete a customer group

To delete a customer group, send a DELETE request to the /api/customer_groups/{{id}} endpoint, where {{id}} is the id of the resource that you want to delete.

Example request:
DELETE /api/customer_groups/1234 HTTP/1.1
Accept: application/vnd.api+json
Example response:
HTTP/1.1 204 No Content