Abenity Perks API
The Abenity Perks API allows you to gather information about the categories of offers in Abenity, as well as key information about the brands and their discount offers. You can then present that content to your members right within your own platform, making it the center of your members' savings experience.
The feed does not provide full offer redemption details. It is intended to be used as a way to advertise offers within your platform, and then deep link your members to those offers' full redemption details within your branded, Abenity-hosted discount program. API Usage is governed by the API Terms.
Contents:
Introduction
Getting Started
The Abenity Perks API is a RESTful interface that allows you to access your discount offers as JSON-formatted data, suitable for integration into your existing software.
To get started developing with the Abenity Perks API you will need to meet the following requirements:
- Have an active account that supports Perks API integration. Sign Up Now.
- Have Perks API credentials. These can be obtained from your Client Executive.
Usage
The Abenity Perks API is intended to be consumed as a daily data feed, and not as a real-time method for fetching and passing through offer details in your application. For example, a standard implementation should fetch the categories from the categories.json endpoint and then store this data for future requests. To build out a full offer database of offers, each category should be requested from the offers endpoint through a request like offers.json?category_id=4. Once all data has been downloaded, you may build your own browsing experience on top of this data without any additional requests to the Perks API data feed being required.
Security
In order to provide our clients and their members with the most secure system, the latest encryption technology must be used in order to interact with our API. Currently, this means using TLS v1.2 or higher to encrypt your HTTPS connection to the API. If your system uses outdated encryption technology you will receive a HTTP "426 Upgrade Required" error response.
Authentication
API requests are authenticated using HTTP Basic Authentication. The username, which is essentially an API key, must be requested from your Client Executive (This will be different than any other usernames within your program). The password will always be clientapp.
Rate Limit
Requests are limited to 200 requests per unique URL per client IP address per 24 hours. For example, if the categories.json endpoint is called over 200 times within a 24-hour period from the same IP address, then after the limit has been exceeded the endpoint will return an HTTP 429 "Too Many Requests" response. As time goes by and the previous requests fall outside the previous 24-hour window, then more requests will be available to be processed again.
Sample Application
Below is an example of how the Perks API can be used to display category navigation and offers featuring the name and logo of the merchant. Offers are linked to the Perks program and can even be integrated with Single Sign-On and deep linking to authenticate your members and take them directly to the offer redemption instructions.
Methods
All API requests should originate from your Perks Program's domain, i.e. if you access your Abenity Perks at https://acme.abenity.com, then all API requests should also be sent to acme.abenity.com over HTTPS.
Each of these endpoints will return a Last-Modified and Expires HTTP header to indicate the currency of the data.
Categories
GET /discounts/api/v2.2/feed/categories.json
This endpoint will return an object containing all of the offer categories in your Discount Program.
Example
# Request
curl -X GET -u X3dh4BdWpzny9Vm65ZnwIsRTkdMX5UAw:clientapp \
https://acme.abenity.com/discounts/api/v2.2/feed/categories.json
# Response
HTTP/1.1 200 OK
[
{
"id": 322,
"key": "Attractions_and_Tours",
"title": "Attractions & Tours",
"offer_count": 406,
"merchant_count": 329,
"children": [
{
"id": 339,
"key": "Attractions_and_Tours/Dinner_Theaters",
"title": "Dinner Theaters",
"offer_count": 9,
"merchant_count": 9,
"children": null
},
{
"id": 347,
"key": "Attractions_and_Tours/Experiences",
"title": "Experiences",
"offer_count": 21,
"merchant_count": 19,
"children": null
},
{
"id": 340,
"key": "Attractions_and_Tours/Museums",
"title": "Museums",
"offer_count": 60,
"merchant_count": 52,
"children": null
},
{
"id": 397,
"key": "Attractions_and_Tours/Ski_Resorts",
"title": "Ski Resorts",
"offer_count": 8,
"merchant_count": 8,
"children": null
},
{
"id": 341,
"key": "Attractions_and_Tours/Tours_and_Sightseeing",
"title": "Tours & Sightseeing",
"offer_count": 152,
"merchant_count": 120,
"children": null
},
{
"id": 342,
"key": "Attractions_and_Tours/Water_Parks_and_Theme_Parks",
"title": "Water Parks & Theme Parks",
"offer_count": 116,
"merchant_count": 101,
"children": null
},
{
"id": 343,
"key": "Attractions_and_Tours/Zoos_and_Aquariums",
"title": "Zoos & Aquariums",
"offer_count": 40,
"merchant_count": 20,
"children": null
}
]
},
{
"id": 4,
"key": "Automotive",
"title": "Automotive",
"offer_count": 13251,
"merchant_count": 11804,
"children": [
{
"id": 98,
"key": "Automotive/Accessories",
"title": "Accessories",
"offer_count": 1644,
"merchant_count": 1020,
"children": null
},
{
"id": 412,
"key": "Automotive/Auto_Loans",
"title": "Auto Loans",
"offer_count": 1,
"merchant_count": 1,
"children": null
},
{
"id": 165,
"key": "Automotive/Gas_Stations",
"title": "Gas Stations",
"offer_count": 163,
"merchant_count": 163,
"children": null
},
{
"id": 50,
"key": "Automotive/Maintenance_and_Repair",
"title": "Maintenance & Repair",
"offer_count": 10732,
"merchant_count": 10032,
"children": null
},
{
"id": 51,
"key": "Automotive/New_and_Used_Cars",
"title": "New & Used Cars",
"offer_count": 561,
"merchant_count": 450,
"children": null
},
{
"id": 108,
"key": "Automotive/Roadside_Assistance",
"title": "Roadside Assistance",
"offer_count": 46,
"merchant_count": 42,
"children": null
},
{
"id": 105,
"key": "Automotive/Services",
"title": "Services",
"offer_count": 104,
"merchant_count": 96,
"children": null
}
]
}
...
]Offers within a Category
GET /discounts/api/v2.2/feed/offers.json
Get the discount offer listings within a specific category. You may use this information to advertise discount listings on your site. Use the "link" parameter in the response to direct your members to the full offer listing with redemption instructions within your program.
| Parameter | Definition | Example |
| category_id or category_key | Use the id or key returned from the Categories endpoint in order to get the offers within that category. | 105 or Automotive/Services |
| count | Optional. Set this parameter to a positive integer to limit the results. This can be used to improve the response time. | 100 |
| page | Optional. Set this parameter to a value of 1 or more to define a page of results. | 2 |
Example
# Request
curl -X GET -u X3dh4BdWpzny9Vm65ZnwIsRTkdMX5UAw:clientapp \
https://acme.abenity.com/discounts/api/v2.2/feed/offers.json?category_id=4&count=100&page=2
# Response
HTTP/1.1 200 OK
[
{
"merchant": {
"name": "Windshield Replacers",
"id": 123,
"logo": {
"url": "http://abenity.s3.amazonaws.com/vendor/assets/logos/local-merchant@2x.png",
"width": 306,
"height": 96
}
},
"offers": [
{
"category_id": 50,
"exp_date": "2017-07-03",
"locations": [
{
"name": "",
"address": "495 1st Street",
"city": "Idaho Falls",
"state": "ID",
"zip": "83401",
"country": "US",
"latitude": 43.497135,
"longitude": -112.024162,
"coordinate_accuracy": "address",
"arcgis_score": null,
"phone": "208-525-3230",
"fax": "",
"id": 107508475
}
],
"days_old": 65,
"id": 106398676,
"title": "FREE Chip Repair with your comprehensive insurance",
"link": "https://acme.abenity.com/discounts/offer/10:1662479"
},
{
"category_id": 50,
"exp_date": "2017-07-03",
"locations": [
{
"name": "",
"address": "495 1st Street",
"city": "Idaho Falls",
"state": "ID",
"zip": "83401",
"country": "US",
"latitude": 43.497135,
"longitude": -112.024162,
"coordinate_accuracy": "address",
"arcgis_score": null,
"phone": "208-525-3230",
"fax": "",
"id": 107508475
}
],
"days_old": 65,
"id": 106398677,
"title": "$24.95 Cash Chip Repair",
"link": "https://acme.abenity.com/discounts/offer/10:1662480"
},
{
"category_id": 50,
"exp_date": "2017-07-03",
"locations": [
{
"name": "",
"address": "495 1st Street",
"city": "Idaho Falls",
"state": "ID",
"zip": "83401",
"country": "US",
"latitude": 43.497135,
"longitude": -112.024162,
"coordinate_accuracy": "address",
"arcgis_score": null,
"phone": "208-525-3230",
"fax": "",
"id": 107508475
}
],
"days_old": 65,
"id": 106398678,
"title": "Up to $150 Cash Back on your Windshield Replacement",
"link": "https://acme.abenity.com/discounts/offer/10:1852274"
}
]
}
...
]Frequently Asked Questions
Q: How often does data change?
A: The active offer database is recompiled every 24 hours around 4:30AM Central Time. It is recommended that you request new data every day after this time.
Version History
Version 2 (Released 11/27/2017)
- The initial version of the Perks API was released as Version 2 because it was an extension to an existing API endpoint.
Version 2.1 (Released 6/23/2020)
- Set strict data types (integer, float) in JSON response
- Removed escaping of forward slashes from JSON (i.e. "https://" is no longer represented as "https:\/\/")
- Added support for pagination of offers
Version 2.2 (Released 7/24/2020)
- Refactored Offers response to use the key name "merchant" instead of "vendor" to match a terminology change across our system.
- The "link" parameter of offers was updated to use https instead of http.