7 Guidelines‎ > ‎

Distribution API upgrade guide

These guide is on targeted only for distributors using older Adility API.

Glossary of changed entities

 Old API New API Meaning
 ProductOffer Offer that merchant provides, e.g.
 Deal - Offer that is scheduled on specific dates within specific deal area
 Business Advertiser Merchants that provides offers
 Deal Area - Specific defined area in US
 - Location Specific location that has its own street address, zip code, latitude and longitude.
 External Order ID Order Number order identifier in distributor’s software
 Product ID Offer ID 
 Physical voucher/productNot supported 
 Digital voucher/product Deal 

What are main differences?
  1. Some of entities are renamed, described above.
  2. There is no more such concept — deal area, you have to find offers by specific location and radius.
  3. With new API it is possible to cancel orders and separate vouchers. Cancelation is required to be implemented on distributor side to get production access.
  4. Special methods presented for checking inventory status: “recently updated”, “recently closed” and “recently published”. So it is assumed you have local copy of Adility database and updated it using these 3 methods.
  5. Different offer types are introduced. Each offer has a type of deal, coupon or gift card. You could always queue for specific type offers or multiple ones.
  6. Nationwide offers are available now and shown by default for each locations.

Suggested workflow for new API

  1. Check which locations, offers categories and offer type you’d like to support, save this information locally.
  2. Grab offer information for all that locations/categories/types once and store it on your side, so you’ll have kind of a copy of Adility but just for specific areas/categories/types.
  3. There are 3 helpful offer search filters: “recently published”, “recently updated” and “recently closed” (see details on http://apidoc.adility.com/distribution-api). You should pull these 3 in background each day to check for updates and update your local offers database in appropriate way.
  4. By default offer info is provided without merchant’s redemption locations, so after you’ve picked specific offers to show to your customers you’ll need to do another API call (get offer details by ID) for every selected offer to get full details including redemption location street addresses. Charge customers and than place orders to Adility, to notify Adility about the purchase and get vouchers in return.
  5. Cancel whole orders or specific vouchers via API if you’ll need to.
In this case your application will work with Adility in kind of asynchronous way with weak dependencies, so potential temporary connectivity issues with Adility won’t cause problem to you, also you won’t be much dependent on speed of getting Offers through API since you’ll store them locally and will just need to get updated info each day.

API Migration steps

  1. Implement new API and test it using sandbox server, most important part here is queueing for offers by specific location and updating offers details.
  2. Leave old your old products database present for backward-compatibility and reporting, create new storage for new Adility offers.
  3. Updated your oders system so that order could be mapped either to older products catalog you have or to new one.