Customer Segments

Customer Segments


The Button Customers API creates one view of your customers for the purpose of being able to commission and target based on their history as a Customer of yours. This often includes the use of segments such as:

  • New Customers
  • Active Customers
  • Future: Any other Customer Segments you want to create

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

Button App Store


Customer Segments allow you to offer different rates based on a Customer's past purchase behavior; rewarding publishers for sending new customers and reducing the cost of re-engaging existing customers.

Some features of Customer Segments with the Button Customers API:

Truly Incremental Acquisition: Ensure spending is truly incremental by offering different rates for "new" and "existing" customer segments.

Global Customer Segmentation: Only pay elevated "New User" rates for users that have never purchased before.

Real-Time Customer Segment Enrollment: Ensure that Customers are removed from "New" segments immediately, even when purchases do not come through Button or are not mobile.

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.

Button App Store

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.
  • last_purchase_date: If known, the ISO8601 timestamp of last purchase by this customer.

In the example above, there are two customers:

  • 1067: The hash was generated from the address
  • 9055: The hash was generated from the address

The definition of each segment will be established with your Button representative during onboarding. Here is a typical configuration:

  • Active: Customers that have made a purchase.
  • New: The default for all other customers.

Integrate the Button Customers API into your system

Integrating ongoing segmentation involves one simple addition to your current Button API integration:

  • Include the Customer ID (your ID is fine) and the user's hashed email in the Order API when Customers purchase

This should be a relatively small amount of work and will be supported by the Button Clients for Node.js, Ruby, and Python. For more information, check out the Customer API full documentation.

Note: If you don’t currently use one of our client libraries, this could be a great time to switch over as we will be trying to make feature improvements as free as possible when using this path.

Reporting Customer with Button Order Reports

This is a simple modification to your existing call to the Button Orders API. Add your Customer ID for the user. This is your internal Customer ID, no need to worry about the Button Customer ID.

The upcoming version of the Button Client Libraries will accept the new value customer_id to all Order calls.

    "btn_ref": "srctok-xxxxx",
    "amount": 2300,
    "customer": {
        "id": "1067",
        "email_sha256": "e233d4a29013e9d87150c6237c6777bedf379ebf1acdc5d6126fec7e8bb74fb5",
        "device_id": "XXXX-XXXXXX-XXX-XXXXXX"

The simplest way to integrate Order Reporting with Customer Segments is using our Order Integration tool with the Button Client Libraries. For more information, check out the Order API full documentation.

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.