Customer groups

Customer groups can be used to group and segment your customers. For example you could organise your customers by their tier “Free”, “Growth, “Enterprise” or make use of groups to keep track of customers trialing beta features.

Customers can belong to one or many groups. You can filter customer threads by group, allowing you to quickly focus on a subset of them.

This guide will show you how to add customers to groups using the API. You can also do this with the UI in Plain if you prefer.

This guide assumes you’ve already created some customer groups in Settings → Customer Groups.

Add a customer to groups

A customer can be added to a customer group using the addCustomerToCustomerGroup mutation.

Depending on what your customer groups are you may want to call this API at different times. For example if you are grouping them by their pricing tier you will want to do this every time their tier changes.

This operation requires the following permissions:

customer:create
customer:edit

import { PlainClient } from '@team-plain/typescript-sdk';

const client = new PlainClient({ apiKey: 'plainApiKey_xxx' });

const res = await client.addCustomerToCustomerGroups({
  customerId: 'c_01GTC6ZHCMAGR06FMPN9VY5J95',
  customerGroupIdentifiers: [
    {
      customerGroupKey: 'free-tier',
    },
    {
      customerGroupKey: 'design-partner',
    },
  ],
});

if (res.error) {
  console.error(res.error);
} else {
  console.log(res.data);
}

Running the above would console.log:

[
  {
    customerId: 'c_01GTC6ZHCMAGR06FMPN9VY5J95',
    createdAt: {
      __typename: 'DateTime',
      iso8601: '2023-06-21T14:20:12.014Z',
      unixTimestamp: '1687357212014',
    },
    createdBy: {
      __typename: 'MachineUserActor',
      machineUserId: 'mu_01H1P0P0PHA2BJRRS7EC02XKCF',
    },
    updatedAt: {
      __typename: 'DateTime',
      iso8601: '2023-06-21T14:20:12.014Z',
      unixTimestamp: '1687357212014',
    },
    updatedBy: {
      __typename: 'MachineUserActor',
      machineUserId: 'mu_01H1P0P0PHA2BJRRS7EC02XKCF',
    },
    customerGroup: {
      id: 'cg_01H1P1RK22WTVMFRY8BX6S6VJX',
      name: 'free tier',
      key: 'free-tier',
      color: '#E78450',
    },
  },
  {
    customerId: 'c_01GTC6ZHCMAGR06FMPN9VY5J95',
    createdAt: {
      __typename: 'DateTime',
      iso8601: '2023-06-21T14:20:12.014Z',
      unixTimestamp: '1687357212014',
    },
    createdBy: {
      __typename: 'MachineUserActor',
      machineUserId: 'mu_01H1P0P0PHA2BJRRS7EC02XKCF',
    },
    updatedAt: {
      __typename: 'DateTime',
      iso8601: '2023-06-21T14:20:12.014Z',
      unixTimestamp: '1687357212014',
    },
    updatedBy: {
      __typename: 'MachineUserActor',
      machineUserId: 'mu_01H1P0P0PHA2BJRRS7EC02XKCF',
    },
    customerGroup: {
      id: 'cg_01H1P1S2HD9PERNNS591ZT28ZZ',
      name: 'design partner',
      key: 'design-partner',
      color: '#FBBF24',
    },
  },
];

import { PlainClient } from '@team-plain/typescript-sdk';

const client = new PlainClient({ apiKey: 'plainApiKey_xxx' });

const res = await client.addCustomerToCustomerGroups({
  customerId: 'c_01GTC6ZHCMAGR06FMPN9VY5J95',
  customerGroupIdentifiers: [
    {
      customerGroupKey: 'free-tier',
    },
    {
      customerGroupKey: 'design-partner',
    },
  ],
});

if (res.error) {
  console.error(res.error);
} else {
  console.log(res.data);
}

Running the above would console.log:

[
  {
    customerId: 'c_01GTC6ZHCMAGR06FMPN9VY5J95',
    createdAt: {
      __typename: 'DateTime',
      iso8601: '2023-06-21T14:20:12.014Z',
      unixTimestamp: '1687357212014',
    },
    createdBy: {
      __typename: 'MachineUserActor',
      machineUserId: 'mu_01H1P0P0PHA2BJRRS7EC02XKCF',
    },
    updatedAt: {
      __typename: 'DateTime',
      iso8601: '2023-06-21T14:20:12.014Z',
      unixTimestamp: '1687357212014',
    },
    updatedBy: {
      __typename: 'MachineUserActor',
      machineUserId: 'mu_01H1P0P0PHA2BJRRS7EC02XKCF',
    },
    customerGroup: {
      id: 'cg_01H1P1RK22WTVMFRY8BX6S6VJX',
      name: 'free tier',
      key: 'free-tier',
      color: '#E78450',
    },
  },
  {
    customerId: 'c_01GTC6ZHCMAGR06FMPN9VY5J95',
    createdAt: {
      __typename: 'DateTime',
      iso8601: '2023-06-21T14:20:12.014Z',
      unixTimestamp: '1687357212014',
    },
    createdBy: {
      __typename: 'MachineUserActor',
      machineUserId: 'mu_01H1P0P0PHA2BJRRS7EC02XKCF',
    },
    updatedAt: {
      __typename: 'DateTime',
      iso8601: '2023-06-21T14:20:12.014Z',
      unixTimestamp: '1687357212014',
    },
    updatedBy: {
      __typename: 'MachineUserActor',
      machineUserId: 'mu_01H1P0P0PHA2BJRRS7EC02XKCF',
    },
    customerGroup: {
      id: 'cg_01H1P1S2HD9PERNNS591ZT28ZZ',
      name: 'design partner',
      key: 'design-partner',
      color: '#FBBF24',
    },
  },
];

Mutation
mutation addCustomerToCustomerGroup($input: AddCustomerToCustomerGroupsInput!) {
  addCustomerToCustomerGroups(input: $input) {
    customerGroupMemberships {
      customerGroup {
        id
        name
        key
        color
      }
    }
    error {
      message
      code
      type
      fields {
        field
        message
        type
      }
    }
  }
}

Variables
{
  "input": {
    "customerId": "c_01GTC6ZHCMAGR06FMPN9VY5J95",
    "customerGroupIdentifiers": [
      {
        "customerGroupKey": "free-tier"
      },
      {
        "customerGroupKey": "design-partner"
      }
    ]
  }
}

If you prefer you can also use the customer group id instead of the key. You can do this like so:

Variables
{
  "input": {
    "customerId": "c_01GTC6ZHCMAGR06FMPN9VY5J95",
    "customerGroupIdentifiers": [
      {
        "customerGroupId": "cg_01GX8H2BWS7Z4EP9RRGMF9NXX2"
      }
    ]
  }
}

Response
{
  "data": {
    "customerGroupMemberships": [
      {
        "customerGroup": {
          "id": "cg_01GX8H2BWS7Z4EP9RRGMF9NXX2",
          "name": "Free Tier",
          "key": "free-tier",
          "color": "#1D4ED8"
        }
      },
      {
        "customerGroup": {
          "id": "cg_05GXF4FGGS2Z7EW9RRGKL9NLL9",
          "name": "Design partner",
          "key": "design-partner",
          "color": "#06B6D4"
        }
      }
    ],
    "error": null
  }
}

Remove a customer from groups

A customer can be removed from a customer group by using the removeCustomerFromGroup mutation.

import { PlainClient } from '@team-plain/typescript-sdk';

const client = new PlainClient({ apiKey: 'plainApiKey_xxx' });

const res = await client.removeCustomerFromCustomerGroups({
  customerId: 'c_01H1P4TE62AS5KZ4CZFC0578ED',
  customerGroupIdentifiers: [
    {
      customerGroupKey: 'free-tier',
    },
    {
      customerGroupKey: 'design-partner',
    },
  ],
});

if (res.error) {
  console.error(res.error);
} else {
  console.log(res.data);
}

Which if successful will console.log null

import { PlainClient } from '@team-plain/typescript-sdk';

const client = new PlainClient({ apiKey: 'plainApiKey_xxx' });

const res = await client.removeCustomerFromCustomerGroups({
  customerId: 'c_01H1P4TE62AS5KZ4CZFC0578ED',
  customerGroupIdentifiers: [
    {
      customerGroupKey: 'free-tier',
    },
    {
      customerGroupKey: 'design-partner',
    },
  ],
});

if (res.error) {
  console.error(res.error);
} else {
  console.log(res.data);
}

Which if successful will console.log null

Mutation
mutation removeCustomerFromCustomerGroup($input: RemoveCustomerFromCustomerGroupsInput!) {
  removeCustomerFromCustomerGroups(input: $input) {
    error {
      message
      code
      type
      fields {
        field
        message
        type
      }
    }
  }
}

Variables
{
  "input": {
    "customerId": "c_01GTC6ZHCMAGR06FMPN9VY5J95",
    "customerGroupIdentifiers": [
      {
        "customerGroupKey": "free-tier"
      },
      {
        "customerGroupKey": "design-partner"
      }
    ]
  }
}

Response
{
  "data": {
    "error": null
  }
}

If you prefer you can also use the customer group id instead of the key. You can do this like so:

Variables
{
  "input": {
    "customerId": "c_01GTC6ZHCMAGR06FMPN9VY5J95",
    "customerGroupIdentifiers": [
      {
        "customerGroupId": "cg_01GX8H2BWS7Z4EP9RRGMF9NXX2"
      }
    ]
  }
}

GraphQL

Reference

Add a customer to groups

Remove a customer from groups

GraphQL

Reference

​Add a customer to groups

​Remove a customer from groups

Add a customer to groups

Remove a customer from groups