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

🚧

Authentication

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:

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

Merchant Offers

Offers

Display Parameters

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

{
    "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.

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

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.