Offers API Integration

Structure Your Request Payload

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

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 Parameter	Description	Required?
`user_id`	Your stable ID for the user, a string between 1 and 255 characters long in the ASCII range `[0x21-0x7E]`. This should be the same ID that is passed into the Button SDK when configuring user attribution.	Yes
`device_ids`	List of 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 (email hashes + device IDs).	No
`email_sha256s`	List of SHA256 email hashes associated with the user, as a 64-character hex string. Downcase and trim any whitespace of the email address prior to hashing. Note: The API accepts at most 10 identifiers.	No
`merchant_id`	You can filter the returned offers by a specific brand by passing the brand organization ID. If this isn’t included, the Offers API will return offers for all brands.	No

Interpreting a Response

Requests made to the Offers 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

Field	Description
`meta`	Property containing `status` field of response
`object`	Property containing merchant_offers collection

Merchant Offers

Field	Description
`merchant_id`	The unique identifier for the brand
`offers`	A collection of offers available for that brand.

Offers

Field	Description	Field Type
`id`	A globally unique identifier for an offer instance. Future requests showing the same offer will contain a unique id (max 255 characters)	string
`rank`	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.	integer
`rate_percent`	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.	string
`rate_fixed`	The fixed commission you will receive for a purchase against the offer. A value of "10" means $10.	string
`currency`	Three-letter ISO currency code if `rate_fixed` (if available), as specified in ISO 4217.	string
`display_params`	Parameters used by the brand to describe the product. These are subject to change by the Brand.

Display Parameters

Field	Description	Field Type
`category`	For brands that offer category specific commissions, you’ll receive an array of offers, each including the category name in this field.	string

Here is an example of a successful response body from the Offers 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 Offers 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.