Fetch Personalized Offers For Your Users

Fetch Personalized Offers For Your Users


In this section, we'll walk through the steps needed to render personalized offers to your users using the Button Personalization API.


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

Note: You'll need to authenticate your API requests; see our authentication reference for more details.


Your request body is then comprised of the following parameters:


Request ParameterDescription
user_idRequired – Your stable ID for the user, a string up to 255 characters long. 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
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.
currencystring – Three-letter ISO currency code of rate_fixed (if available), as specified in ISO 4217.
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",
          "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",
          "offers": [
            {
              "id": "offer-002-0",
              "rank": 2,        
              "rate_fixed": "6",
              "currency": "USD"
            }
          ]
        }
      ]
    }
  }

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