Customer Segments on
All Platforms

Customer Segments

Button Customer Segments unlock revenue through greater commissions for new Customers of your Merchant partners.

  • Receive enhanced commissions for "New" Customers for a Merchant
  • Allow targetted offers to "New" Customers.

The Customers API offers real-time segmentation of Customers with no ongoing incremental work (i.e. no manual “resegmentation”), we slot new Customers in as you report them to us and automatically migrate users between segments as they purchase in Merchants.

In this guide, we'll go over:

How Customer Segments work

Customer Segments work by matching your Customers, with one-way-hashed data, to the Customers of the Merchant partners that you work with. We can then determine at the time of commissioning that the user was a new or active Customer of the Merchant and commission appropriately.

Note: Only select Merchants support Customer Segments today. Contact us for more information about whether the partners you work with support Customer Segments


Customer Segments allow you to offer different rates based on a Customer's past purchase behavior with individual Merchants, while understanding and giving a better view of your own Customers.

Some features of Customer Segments with the Button Customers API:

Enhanced Commissions: Merchants offer improved rates for new users. This allows you to make more commission for the Customers you send!

Global Customer Segmentation: Integrate the Customers API and match Customers to all Merchants.

Real-Time Customer Segment Enrollment: Ensure that Customers' segment-membership is real-time and new users of your product can get improved rates immediately!

Implementation Steps

Setting up Button Customer Segments with the Customers API requires some work in your system to report Customers to Button, as well as a one-time “Initial Import” of your Customers to ensure correct segment membership from the get-go.

Initial Customer Import

To begin segmenting, we need to upload a list of existing Customers. This can be done using the Button Customer Segment uploader.

The uploader accepts CSV format files with the following fields:

  • user_id: Your unique, stable identifier for this customer. Typically this is a numeric ID or unique string.
  • email_sha256: For correlation purposes, the SHA-256 hash of the customer's lowercase e-mail address, as a 64-character hex string. Important: The value of the e-mail address must be converted to lowercase before computing the hash. The hash itself may use uppercase or lowercase hex characters. Internally, Button always normalizes the hash to lowercase.

As you partner with Merchants, your Customers will be segmented within each of these Merchant's user bases:

  • Active: Users that match a Customer that has Purchased in the Merchant.
  • New: The default for all other Users.

Reporting New Customers at Signup

This is a new call to the Button API using your existing API key and will be supported by the Button Client Library in your language of choice.

You should report all new Customers in your “Sign Up” flow -- this ensures that we have the most up-to-date information about your Customers to provide correct rates.

The full list of fields for the Customers API matches the original import, but is slightly differently formatted.

id // your customer ID
email_sha256 // SHA256 hashed email
emails_sha256 // array of SHA256 hashed emails
advertising_id // The IDFA / Android ID of the device

You can find the full API interface in the Customers API Reference.

Receiving Customer Segment Updates

A new type of Webhook will allow you to receive notifications for Customer segment movements for your users. You can configure this on the Webhooks page in the Dashboard.

    "type": "segment-change",
    "customer_id": "customer-123",
    "segments": {
        "previous": [
              "id": "segment-1234",
              "organization_id": "org-4567",
              "name": "new"
        "current": [
            "id": "segment-7890",
            "organization_id": "org-4567",
            "name": "active"
    "timestamp": "2017-03-27T20:29:04.494Z"

Data and Privacy

Button Customer Segment data is stored securely in accordance with all industry best-practices. All data is encrypted and Customer data is never exposed to any other party -- segment membership is used only to determine rates, user offers and to operate affiliation correctly. For additional peace-of-mind, you can maintain all segments against hashed data.