Offers API Best Practices

When to make this request

The Offers API is a server-side integration between the Publisher CMS and Button. Upon client-side initialization ( iOS / Android )the Publisher CMS should call Button’s Offers API in the appropriate request format with the required fields. Button will use the identifiers to determine offers the user is eligible for with partnered Brands, and return the full list of eligible offers. These offers can then be served back to the client-side to load the initial rendering of offers for your user.

API Call Frequency

The Offers API should be called every time a user requests to view on behalf of each user prior to showing the user an offer. Every time your client calls your CMS for an offer to display, you should also be calling Button to identify the optimal rate to show for that specific user. The Offers API has a rate limit of 5,000 requests per minute.

Optimize for Low Latency

The Button Offers API has an average latency of ~100ms. To ensure optimal performance, keep TCP connections alive and reuse them when possible via connection pooling. If connection pooling is not used, new connections + TLS handshakes result in multi-roundtrip operation between the client and server and therefore higher latency when making these API calls.

Caching

Do not cache when using the Offers API. Since a user can change audiences at any time, you do not want to cache the rates you receive. You should fetch from the Offers API each time a user initializes a session with your application.

Retry Logic

If you do not receive a response from the Offers API, you should employ a retry strategy with a cap and backoff. Button recommends waiting to display rates to users until you receive a response.

Tracking Commission from Publisher Offers

As a helpful way to track commissions for the offers being tapped, the Offers API responds with an id for every item within the offers collection. On the client-side, this offer ID can then be set in the pubRef property as part of the PurchasePathRequest when interacting with the Button SDK. If a transaction takes place downstream from one of your Publisher offers, you’ll be able to see this offer ID when ingesting Button webhooks for finalizing commissions back to the user selected the offer.

We have found most Publishers leverage the pubRef field most effectively when they encode this offer id along with the listed commission against their click ID.

Constructing Offers

When constructing an offer, the Offers API also provides a display_params property wherever possible within the offers collection items. Information in this property is often used when populating Brand offer templates shown to users. Since information within display_params is subject to change at the Brand’s discretion, we do not recommend using display_params as a way to reference offers within a Publisher’s CMS. Instead, a Publisher can use the merchant_id when mapping offers being stored within a Publisher’s CMS from the Offers API.