Personalized Rates

Personalized Rates

Personalized Rates lets Button Publishers retrieve dynamic, promotional rates/offers to targeted users with little to no configuration required. Rates can be adjusted on-the-fly based on user audience and Brand promotions, without the need for Button Publishers to manually update their CMS to provide new rates to users.

Brands can create campaigns that target specific cohorts of users and products with different rates. Publishers will receive the rates as soon as they are live within Button and present the new rates to users in real-time.

Product Diagram

This guide walks you through how to utilize the Personalized Rates API. We'll cover:

  1. Key benefits
  2. Getting rates for a user
  3. Best practices
  4. Example

Note: To get started with Personalized Rates, contact your Button Partner Success Manager today.


Key Benefits

  • Unlock more revenue opportunities by serving higher rates to valuable user audiences
  • Personalize offers for each of your users based on their eligibility
  • Access the best rates in real-time from your Brand partners
  • Boost user engagement by giving your users what they want—the best possible offers


Side by Side Comparison


Getting Rates for a User

Personalized Rates is a server-side API integration. Upon a user opening the app, the Publisher should call the Personalized Rates API with the user's Publisher user ID, hashed email(s), and device ID(s). Button will use the identifiers to determine offers the user is eligible for with partnered Brands, and return the full list of eligible rates/offers. These rates may depend on the audiences the Brand wants to target, and negotiated rates between the Publisher and Brand.

You can find your API key here in the Dashboard.

Request Parameters

The Personalized Rates API accepts the following parameters when requesting rates/offers:

  • user_id: Publisher’s ID for the user.
  • device_ids: (optional) List of devices IDs associated with the user.
  • email_sha256s: (optional) List of SHA256 email hashes associated with the user.
  • merchant_id: (optional) Brand organization ID to restrict user offers to.

Best practices

API Request Parameters

  • Pass both the user’s hashed email and device ID to the Personalized Rates API. The rationale here is that some Brands will only pass hashed emails or device IDs to Button. As such, you will want to pass both to ensure the highest match rate between your users and the Brand’s users.
  • Be sure to downcase and strip the email address prior to hashing.
  • Be sure to strip the device ID prior to passing it to the API.

API Call Frequency

  • Call the API on behalf of each user prior to showing the user a rate.
  • Every time your client calls your server for an offer to display, you should be calling Button beforehand for a rate to be included in that display.
  • If retrieving rates for all Brands, do not include the Brand (merchant_id) in the request.
  • If a merchant_id comes back in the response that you do not recognize, use the Merchants API to get the Brand’s details (Brand name, homepage URL, icon URL).
  • If retrieving rates for one Brand, include the Brand (merchant_id) in the request.

Calling the API Server-side

  • Call the API server-side to determine your commission rate for a given Brand and apply logic to determine the user’s commission rate. Include the user’s commission rate in the offer details that are sent from your CMS to the client.

Optimize for Low Latency

  • Keep TCP connections alive and reuse them when possible. In other words, use connection pools. For reference, a new connection + TLS handshake is a multi-roundtrip operation (client ←→ server), which can contribute to higher latency when making these API calls.

Caching

  • Do not cache when using this API. Since a user can change audiences at any time, you do not want to cache the rates you receive from our API.

Commissioning and Constructing Offers

  • You can store the offers[].id (the offer ID) along with the commission rate against your click ID, which you pass to our SDK in the pubRef field upon routing a user to a given Brand. If a transaction takes place, you’ll see both the pubRef and the offer ID details in the webhooks you receive from Button. Thus, you’ll be able to reference which offer the user saw when ingesting webhooks from Button, which informs your commissioning logic.
  • The display_params returned by the API are solely to assist you in constructing offers to display to users. The fields can be used to fill in to your existing Brand offer templates that you show to users. Since category names can change, they (e.g. display_params) should not be used as a way to reference offers in your CMS.
  • Assuming you share a specific percentage of your total commission with the user (e.g. 80%), you can rely on the commission amount Button includes in the transaction details.

Example

Sample curl request:

curl https://api.usebutton.com/v1/offers \
  -X POST \
  -u YOUR_API_KEY: \
  -H 'Content-Type: application/json' \
  -d '{
    "user_id": "1234",
    "device_ids": ["AAAAAAAA-AAAA-AAAA-AAAA-AAAAAAAAAAAA"],
    "email_sha256s": ["1234567a1234567a1234567a1234567a1234567a1234567a1234567a1234567a"]
  }'

Sample response:

{
  "meta": {
    "status": "ok"
  },
  "object": {
    "merchant_offers": [
      {
        "merchant_id": "org-merchant-1",
        "best_offer_id": "offer-001-2",
        "offers": [
          {
            "id": "offer-001-0",
            "rate_percent": "5",
            "display_params": {
              "category": "Sports"
            }
          },
          {
            "id": "offer-001-1",
            "rate_percent": "5",
            "display_params": {
              "category": "Outdoors"
            }
          },
          {
            "id": "offer-001-2",
            "rate_percent": "10",
            "display_params": {
              "category": "Baby Products"
            }
          },
          {
            "id": "offer-001-13",
            "rate_percent": "2"
          }
        ]
      },
      {
        "merchant_id": "org-merchant-2",
        "best_offer_id": "offer-002-0",
        "offers": [
          {
            "id": "offer-002-0",
            "rate_percent": "6"
          }
        ]
      }
    ]
  }
}

This offer response means that if this user purchases from org-merchant-1, you will receive:

  • 5% on Sports and Outdoors
  • 10% on Baby Products
  • 2% on all other items

If the user purchases from org-merchant-2, you’ll will receive:

  • 6% on all items
  • Based on what portion you plan to pass along to the user (e.g. 50%), you would then show the user a 3% offer.

You may choose to hand 50% of this incentive back to your users, and would therefore indicate to users that will receive 3% cash back from this Brand.

The full API documentation can be found here.

Note: Rates returned via this API a) only include the commission rate that the Publisher earns, not the rate the user earns and b) does not include “terms and exclusions”. It is the Publisher's responsibility to present these to the user.