Customer Segmentation API (Beta) Guide

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.

Beta access

This API is currently in beta. We may introduce breaking changes without notice. For more information, see Customer Segmentation API (Beta) Overview.

Customer Segments

Create customer segments to offer customers targeted promotions. See the Customer Segmentation overview to get the big picture on targeting customers with promotions. For more granular details, see the Targeting a segment with a promotion section of this article.

Creating segments

Create new segments by sending a request to the Create segments endpoint. Include an array of objects, where each object represents a segment and contains name and description properties.

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

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."
  }
]

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 for each registered customer using the Create shopper profiles endpoint. Include an array of objects, where each object represents a shopper profile and contains the corresponding customer_id.

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
  }
]

New customers

To create a shopper profile for a new customer, first use the 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 endpoint. Include the segmentId as a path parameter, and pass an array of shopper profile ids.

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
]

Updating and deleting segments

Use the following guide to update or delete segments.

Update segments

Update segment names and descriptions using the Update Segments endpoint. Include an array of objects that each contain the segmentId; name and description are optional.

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."
  }
]

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 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.

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

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

Delete segments

To delete segments, use the Delete segments 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.

⚠️

Make sure to specify which segments

If you don't pass the id:in query parameter, you will delete every segment in the store.

Example request: Delete segments

DELETE https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/segments
X-Auth-Token: {{ACCESS_TOKEN}}
Accept: application/json

Delete shopper profiles

To delete shopper profiles, use the Delete shopper profiles endpoint. Include the id:in query parameter to specify which shopper profiles you want to delete.

⚠️

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.

Example request: Delete shopper profiles

DELETE https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/shopper-profiles
X-Auth-Token: {{ACCESS_TOKEN}}
Accept: application/json

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 endpoint. This request returns a list of all shopper profiles belonging to a specific segment.

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

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 endpoint. Include the id of the shopper profile as a path parameter.

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

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 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

When participating in the Customer Segmentation beta while using the Promotions API, you can use the Promotions Advanced Editor in the store control panel to target the segments you create with the Customer Segmentation API.

Promotions Advanced Editor

To create a promotion in the store control panel, go to Marketing > Promotions > Create > With Advanced Editor. For more detailed information on creating a promotion, visit the Advanced Editor (opens in a new tab) article in our Support Center.

Promotions Advanced Editor.png

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

The Advanced 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 Advanced Editor (opens in a new tab) article in our Support Center.