> This page is for Developer.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.bigcommerce.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.bigcommerce.com/_mcp/server.

# Customer Segmentation API Guide

> **Note**
>
> #### Exclusive enterprise feature
>
> The Customer Segmentation API is available to enterprise customers. If you would like to become an enterprise customer, please contact your BigCommerce Customer Service Manager or our support team.

Get started with the Customer Segmentation API by creating *Segments* and *Shopper Profiles*. This guide provides example requests and responses to get you started customizing targeted shopper experiences.

## Customer Segments

Create customer segments to offer customers targeted promotions. See the [Customer Segmentation overview](/developer/docs/admin/customers/customer-segmentation) to get the big picture on targeting customers with promotions. For more granular details, see the [Targeting a segment with a promotion](#targeting-a-segment-with-a-promotion) section of this article.

### Creating segments

Create new segments by sending a request to the [Create segments](/developer/api-reference/rest/admin/management/customer-segmentation/segments/segments-post-request) endpoint. Include an array of objects, where each object represents a segment and contains `name` and `description` properties.

> **Note**
>
> Segment names appear in the Promotions Manager view of the store control panel. To reduce confusion, give your segments unique names.

#### Request

**`Example request: Create segments`**

```http title="Example request: Create segments"
POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/segments
X-Auth Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json

[
  {
    "name": "My Segment",
    "description": "Segment description."
  }
]
```

#### Response

**`Example response: Create segments`**

```json title="Example response: Create segments"
{
  "data": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "name": "My Segment",
      "description": "Segment description.",
      "created_at": "2022-08-24T14:15:22Z",
      "updated_at": "2022-08-24T14:15:22Z"
    }
  ],
  "meta": {}
}
```

## Shopper profiles

Create a shopper profile to assign registered customers to segments. You can identify which registered customer a shopper profile represents by the profile's `customer_id` property; shopper profiles have a 1:1 relationship with registered customers.

### Existing customers

You can create one [shopper profile](/developer/docs/admin/customers/customer-segmentation/definitions-and-relationships#shopper-profile) for each registered customer using the [Create shopper profiles](/developer/api-reference/rest/admin/management/customer-segmentation/shopper-profiles/shopper-profiles-request) endpoint. Include an array of objects, where each object represents a shopper profile and contains the corresponding `customer_id`.

#### Request

**`Example request: Create shopper profiles`**

```http title="Example request: Create shopper profiles"
POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/shopper-profiles
X-Auth Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json

[
  {
    "customer_id": 1
  }
]
```

#### Response

**`Example response: Create shopper profiles`**

```json title="Example response: Create shopper profiles"
{
  "data": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "customer_id": 1,
      "created_at": "2022-08-24T14:15:22Z",
      "updated_at": "2022-08-24T14:15:22Z"
    }
  ],
  "meta": {}
}
```

### New customers

To create a shopper profile for a new customer, first use the [Create customers](/developer/api-reference/rest/admin/management/customers/v3/create-customers) endpoint to register the customer, then create a shopper profile using the new `customer_id`.

### Add shopper profiles to a segment

After you create segments and shopper profiles, you can associate multiple shopper profiles with a given segment using the [Add shopper profiles to a segment](/developer/api-reference/rest/admin/management/customer-segmentation/shopper-profiles-for-a-segment/post-shopper-profile) endpoint. Include the `segmentId` as a path parameter, and pass an array of shopper profile `id`s.

#### Request

**`Example request: Add shoppers to a segment`**

```http title="Example request: Add shoppers to a segment"
POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/segments/{{segmentId}}/shopper-profiles
X-Auth Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json

[
  "497f6eca-6276-4993-bfeb-53cbbbba6f08", // shopper profile UUID
]
```

#### Response

**`Example response: Add shoppers to a segment`**

```json title="Example response: Add shoppers to a segment"
{
  "data": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "customer_id": 1,
      "created_at": "2022-08-24T14:15:22Z",
      "updated_at": "2022-08-26T14:08:31Z"
    }
  ]
}
```

## Updating and deleting segments

Use the following guide to update or delete segments.

### Update segments

Update segment names and descriptions using the [Update Segments](/developer/api-reference/rest/admin/management/customer-segmentation/segments/put-segment-objects) endpoint. Include an array of objects that each contain the `segmentId`; `name` and `description` are optional.

#### Request

**`Example request: Update segments`**

```http title="Example request: Update segments"
PUT https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/segments
X-Auth Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json

[
  {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "My Segment",
    "description": "New and improved segment description."
  }
]
```

#### Response

**`Example response: Update a segment`**

```json title="Example response: Update a segment"
{
  "data": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "name": "My Segment",
      "description": "New and improved segment description.",
      "created_at": "2022-08-24T14:15:22Z",
      "updated_at": "2022-08-27T18:57:22Z"
    }
  ],
  "meta": {}
}
```

#### Remove shoppers from a given segment

You may want to change the segments to which a shopper's profile belongs based on the shopper's behavior on the storefront. To remove one or more specific shopper profiles, use the [Remove shopper profiles from a segment](/developer/api-reference/rest/admin/management/customer-segmentation/shopper-profiles-for-a-segment/delete-shopper-profile) endpoint. Include the `segmentId` as a path parameter, and use the `id:in` query parameter to pass the shopper profile `id`(s) you want to remove. If you exclude `id:in`, this request will empty the segment of all shopper profiles.

> **Note**
>
> Removing a shopper profile from a segment does not delete the shopper profile itself. The shopper profile will remain associated with any other segments.

#### Request

**`Example request: Remove shoppers from a segment`**

```http title="Example request: Remove shoppers from a segment"
DELETE https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/segments/{{segmentId}}/shopper-profiles
X-Auth Token: {{ACCESS_TOKEN}}
Accept: application/json
```

#### Response

**`Example response: Remove shoppers from a segment`**

```json title="Example response: Remove shoppers from a segment"
HTTP 204 No Content
```

### Delete segments

To delete segments, use the [Delete segments](/developer/api-reference/rest/admin/management/customer-segmentation/segments/delete-store-segment) endpoint. Segments and shopper profiles have a many-to-many relationship. Thus, all the shopper profiles associated with a deleted segment will still exist, but be disassociated from the deleted segment. Include the `id:in` query parameter to specify which segments you want to delete.

> **Note**
>
> #### Make sure to specify which segments
>
> If you don't pass the `id:in` query parameter, you will delete every segment in the store.

#### Request

**`Example request: Delete segments`**

```http title="Example request: Delete segments"
DELETE https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/segments
X-Auth-Token: {{ACCESS_TOKEN}}
Accept: application/json
```

#### Response

**`Example response: Delete segments`**

```json title="Example response: Delete segments"
HTTP 204 No Content
```

### Delete shopper profiles

To delete shopper profiles, use the [Delete shopper profiles](/developer/api-reference/rest/admin/management/customer-segmentation/shopper-profiles/delete-store-shopper-profile) endpoint. Include the `id:in` query parameter to specify which shopper profiles you want to delete.

> **Note**
>
> #### Make sure to specify which shopper profiles
>
> If you don't pass the `id:in` query parameter, you will delete every shopper profile in the store.

#### Request

**`Example request: Delete shopper profiles`**

```http title="Example request: Delete shopper profiles"
DELETE https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/shopper-profiles
X-Auth-Token: {{ACCESS_TOKEN}}
Accept: application/json
```

#### Response

**`Example response: Delete shopper profiles`**

```json title="Example response: Delete shopper profiles"
HTTP 204 No Content
```

## Retrieving segment information

Once you've established relationships between segments and shopper profiles, you can extend the reach of the Customer Segmentation API to target customers.

### Retrieve shopper profiles for a segment

To keep your segments in sync with external apps, use the [Get all shopper profiles in a segment](/developer/api-reference/rest/admin/management/customer-segmentation/shopper-profiles/get-shopper-list) endpoint. This request returns a list of all shopper profiles belonging to a specific segment.

#### Request

**`Example request: Get all shopper profiles in a segment`**

```http title="Example request: Get all shopper profiles in a segment"
GET https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/segments/{{segmentId}}/shopper-profiles
X-Auth-Token: {{ACCESS_TOKEN}}
Accept: application/json
```

#### Response

**`Example response: Get all shopper profiles in a segment`**

```json title="Example response: Get all shopper profiles in a segment"
{
  "data": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "customer_id": 1,
      "created_at": "2022-08-24T14:15:22Z",
      "updated_at": "2022-08-24T14:15:22Z"
    }
  ],
  "meta": {
    "pagination": {
      "total": 1,
      "count": 1,
      "per_page": 50,
      "current_page": 1,
      "total_pages": 1
    }
  }
}
```

### Retrieve segments for a shopper profile

To find all segments associated with a given shopper profile, use the [Get all segments for a shopper profile](/developer/api-reference/rest/admin/management/customer-segmentation/segments-for-a-shopper-profile/get-list-shopper-profile) endpoint. Include the `id` of the shopper profile as a path parameter.

#### Request

**`Example request: Get a shopper's segments`**

```http title="Example request: Get a shopper's segments"
GET https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/shopper-profiles/{{shopperProfileId}}/segments
X-Auth-Token: {{ACCESS_TOKEN}}
Accept: application/json
```

#### Response

**`Example response: Get a shopper's segments`**

```json title="Example response: Get a shopper's segments"
{
  "data": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "name": "My Segment",
      "description": "New and improved segment description.",
      "created_at": "2022-08-24T14:15:22Z",
      "updated_at": "2022-08-24T14:15:22Z"
    }
  ],
  "meta": {
    "pagination": {
      "total": 1,
      "count": 1,
      "per_page": 50,
      "current_page": 1,
      "total_pages": 1
    }
  }
}
```

### Retrieve shopper profile and segments for a customer

To discover whether a customer is already associated with a shopper profile and segments, use the [Get customers](/developer/api-reference/rest/admin/management/customers/v3/get-customers) endpoint. Pass the `include` query parameter with `shopper_profile_id` and `segment_ids` as in its comma-separated list of values.

## Targeting a segment with a promotion

You can use the Promotions standard editor in the store control panel to target the segments you create with the Customer Segmentation API.

### Promotions standard editor

To create a promotion in the store control panel, go to **Marketing > Promotions > Create > With standard editor**. For more detailed information on creating a promotion, visit the [standard editor](https://support.bigcommerce.com/s/article/Advanced-Promotions#creating) article in our Support Center.

![Promotions standard editor.png](/_fern-img/c20e24091bed2bd246f964801631a264f1c9fe2016f5b60089fb7ffb0e11fa53.webp)

When you set up targeting rules for a promotion, the **Customer Segment** field is available as an option.

![targeting.png](/_fern-img/12ed93e4d0aa6499a416effa0646d71f73997d27581dd97aca9134536e2573dc.webp)

The standard editor supports both inclusion and exclusion targeting rules, such as the following:

* Using the *is* conditional, a promotion can target segments of shoppers who are in **segment A** *and/or* **segment B**.

- Using the *is not* conditional, a promotion can target segments of shoppers who are in *neither* **segment A** *nor* **segment B**.

To learn more about promotion targeting rules, visit the [standard editor](https://support.bigcommerce.com/s/article/Advanced-Promotions#creating) article in our Support Center.

## Resources

### Articles

* [Customer Segmentation API Overview](/developer/docs/admin/customers/customer-segmentation)
* [Definitions and Logical Relationships](/developer/docs/admin/customers/customer-segmentation/definitions-and-relationships)
* [Promotions API](/developer/docs/admin/customers/customer-segmentation/promotions-api)
* [Promotions standard editor](https://support.bigcommerce.com/s/article/Advanced-Promotions#creating) (Support Center)

### Customer Segmentation reference

* [Customer Segmentation V3 API Reference Overview](/developer/api-reference/rest/admin/management/customer-segmentation)
* [Create segments](/developer/api-reference/rest/admin/management/customer-segmentation/segments/segments-post-request)
* [Create shopper profiles](/developer/api-reference/rest/admin/management/customer-segmentation/shopper-profiles/shopper-profiles-request)
* [Add shopper profiles to a segment](/developer/api-reference/rest/admin/management/customer-segmentation/shopper-profiles-for-a-segment/post-shopper-profile)
* [Update Segments](/developer/api-reference/rest/admin/management/customer-segmentation/segments/put-segment-objects)
* [Remove shopper profiles from a segment](/developer/api-reference/rest/admin/management/customer-segmentation/shopper-profiles-for-a-segment/delete-shopper-profile)
* [Delete segments](/developer/api-reference/rest/admin/management/customer-segmentation/segments/delete-store-segment)
* [Get all shopper profiles in a segment](/developer/api-reference/rest/admin/management/customer-segmentation/shopper-profiles/get-shopper-list)
* [Get all segments for a shopper profile](/developer/api-reference/rest/admin/management/customer-segmentation/segments-for-a-shopper-profile/get-list-shopper-profile)

### Customers reference

* [Create customers](/developer/api-reference/rest/admin/management/customers/v3/create-customers)
* [Get customers](/developer/api-reference/rest/admin/management/customers/v3/get-customers)