Fetch Personalized Offers For Your Users

Fetch Personalized Offers For Your Users


In this section we will walk through the steps needed to render personalized offers to your users using the Button Personalization API


Locate your API key

Interacting with the Personalization API requires authentication using an API key issued through the Button Dashboard.

  • Head over to the Button Dashboard and log in using your Organization’s Button credentials
  • Once logged in, click on your Organization’s drop down icon in the top-right to navigate menu options. Select Organization Settings.
  • Within Organization Settings, scroll down to API Keys and select Generate Key.
  • Give your API Key a name and select Generate.
  • Copy the key generated and store it in your application’s secrets. This key is like a password for your account. You should ensure it is protected within your organization, and never share it publicly.

Now that you have your key generated, you can start using it to request offers from the Button Personalization API.


Authenticating a Request with your API Key

Button expects API key authorization via Basic Auth. In order to construct an Authorization header value, follow these steps:

  1. Add a colon to the end of the api key (e.g. apiKey + ":")
  2. Base64 encode the resulting string
  3. The authorization method and a space i.e. "Basic " is then put before the encoded string. (e.g. "Basic " + base64Encode(apiKey + ":"))

The resulting key/value pair would then look like this:

Initial Load Sequence

Structure Your Request Payload

Here is a sample POST request using the cURL terminal command to report an order to the Button Personalization API. For more information on this API’s specifications, visit the Personalization API


    curl https://pubapi.usebutton.com/v1/offers \
      -X POST \
      -H 'Authorization: "Basic QWxhZGRpbjpPcGVuU2VzYW11"' \
      -H "Content-Type: application/json" \
      -d '{
        "user_id": "some-user-id",
        "device_ids": ["123"],
        "email_sha256s": ["1234567a1234567a1234567a1234567a1234567a1234567a1234567a1234567a"]
      }'


Your request body is then comprised of the following parameters:


Request ParameterDescription
user_idRequired – Your stable ID for the user. This should be the same ID that is passed into the Button SDK when configuring user attribution.
device_idsRequired – List of case-insensitive device advertising IDs associated with the user. These must be either IDFAs for iOS or GAIDs for Android. Trim any whitespace in device advertising ID prior to passing it to the API. Note: The API accepts at most 10 combined identifiers between device_ids and email_sha256s
email_sha256sRequired – List of SHA256 email hashes associated with the user. Downcase and trim any whitespace of the email address prior to hashing. Note: The API accepts at most 10 combined identifiers between device_ids and email_sha256s
merchant_idOptional – You can filter the returned offers by a specific brand by passing the brand organization ID. If this isn’t included, the Personalization API will return offers for all brands.


Interpreting a Response

Requests made to the Personalization API return commission rates owed to the Publisher for driving business to Brands. Publishers, in turn, can decide what percentage of that commission is passed on to the user for shopping there.

Offers Response

FieldDescription
metaProperty containing status field of response
objectProperty containing merchant_offers collection


Merchant Offers

FieldDescription
merchant_idThe unique identifier for the brand
best_offer_idThe offer id for the highest ranking brand offer
offersA collection of offers available for that brand.


Offers

FieldDescription
idstring – A globally unique identifier for an offer instance. Future requests showing the same offer will contain a unique id (max 255 characters
rankinteger – The offer’s rank in terms of relevance to the end user. A lower rank corresponds to higher relevance. Ranks are not scoped to a single brand grouping, but global across the entire response.
rate_percentstring – The percentage commission of a given line item total you will receive for a purchase against the offer. A value of "10" means 10 percent. Note: fixed commissions are currently only supported in USD.
rate_fixedstring – The fixed commission you will receive for a purchase against the offer. A value of "10" means $10.
display_paramsParameters (reference) used by the brand to describe the product. These are subject to change by the Brand.


Display Parameters

FieldDescription
categorystring – For brands that offer category specific commissions, you’ll receive an array of offers, each including the category name in this field.


Here is an example of a successful response body from the Personalization API, displaying a collection of Brand offers:

  // Sample response: 
  {
    "meta": {
      "status": "ok"
    },
    "object": {
      "merchant_offers": [
        {
          "merchant_id": "org-brand-1",
          "best_offer_id": "offer-001-2",
          "offers": [
            {
              "id": "offer-001-2",
              "rank": 1,
              "rate_percent": "10",
              "display_params": {
                "category": "Baby Products"
              }
            },
            {
              "id": "offer-001-0",
              "rank": 3,        
              "rate_percent": "5",
              "display_params": {
                "category": "Sports"
              }
            },
            {
              "id": "offer-001-1",
              "rank": 4,        
              "rate_percent": "5",
              "display_params": {
                "category": "Outdoors"
              }
            },
            {
              "id": "offer-001-13",
              "rank": 5,        
              "rate_percent": "2"
            }
          ]
        },
        {
          "merchant_id": "org-brand-2",
          "best_offer_id": "offer-002-0",
          "offers": [
            {
              "id": "offer-002-0",
              "rank": 2,        
              "rate_fixed": "6"
            }
          ]
        }
      ]
    }
  }

This response indicates that if a Publisher’s user purchases from org-brand-1, the Publisher will receive a 5% commission on Sports and Outdoors, 10% on Baby Products, and 2% on all other items. Likewise, if the user purchases from org-brand-2, the Publisher will receive a $6 commission on all items, since no categories are specified.

It is up to the Publisher’s discretion to decide what percentage is commissioned back to the user for making the purchase. For example, if the Publisher decides to award 50% back to the user for a purchase with org-brand-2, then the user would view a $3 offer while shopping with org-brand-2.

Drive Performance With Offer Rank

The Personalization API response payload provides a rank field proven to drive performance when rendering offers to your end users. These offers are pre-sorted in ascending order, with "1" as the highest ranking offer.

Offers are ranked across brands, allowing brands themselves to be ranked by utilizing min(offers.rank). This can be helpful when your application renders brand offers within an isolated brand view, or all together in a single view.

Here’s how a Publisher application would render an isolated brand view using the example response data from above:


Publisher Isolated Brand View


Because org-brand-1 has the highest ranking offer, they are rendered first. As org-brand-2 has the second highest ranking offer, they would follow.

In the case where a Publisher application renders brand offers together, this is how offers should render using the example data from above.


Publisher Intertwined View