A full list of the currently available coupons can be requested through the /coupons endpoint (GET method). The maximum results served in one request to this endpoint is 100. The response for each call indicates the page requested, maximum results per page, and the total available coupons. Using this information, you can make subsequent calls to this endpoint, each time incrementing the requested page (a parameter sent in the request) until you have all of the available coupons.
This currently available list of coupons is subject to change at any time for the following reasons:
· Reason: The entity offering the coupon cancels the coupons.
o Effect: The coupon will no longer be returned in results from /coupons.
·
Reason:
The coupon reaches it maximum allowed clips.
o Effect: The coupon will no longer be returned in results from /coupons.
· Reason: The entity offering the coupon makes changes to (edits) the coupon.
o Effect: The coupon data will change in results from /coupons. An edited coupon will always retain its ID field.
· Reason: The coupon expires based on its EndDate field.
o Effect: The coupon will no longer be returned in results from /coupons.
In order to maintain an up-to-date list of currently active coupons you will need to both keep your own records of coupons offered through this API and regularly query the API for the currently available coupons in order to keep your records reasonably up-to-date. You will also need to report coupon clips made by your end users (shoppers) regularly.
Requirements:
1. Keep your own records of the coupons . Coupons discovered through this API should be stored in your own data store solution as they are discovered. This API is not designed to be used as an “on-demand” webservice for end-users (shoppers).
2. Maintaining your records. To keep your coupon records up-to-date, we recommend calling /coupons every 15-20 minutes and using the results to update coupons which have changed or remove coupons which are no longer returned in the results. While, as a best practice, we recommend a request interval of 15-20 minutes, we allow an interval of up to 45 minutes on average.
3. Reporting on clips. Your system should report clips regularly, on the same recommended/required interval as requesting the currently available coupons. We recommend an interval of 15-20 minutes, and require the maximum interval to be 45 minutes. See “Reporting Clips (Coupon Claims)” below for more information.
The entities that offer coupons served through this API have a usage limit for each coupons. Once enough end users (shoppers) have clipped/claimed coupons, these coupons are no longer available for further clips/claims. The coupons which have reached their maximum allow clips will no longer be served in calls to /coupons, but will remain usable for those who have already clipped/claimed them until their EndDate passes.
In order for Loyalty Lane to maintain a reasonably up-to-date record of total clips, you will need to report regularly to the /clips (POST method) endpoint. Each call to this endpoint should report on only clips that have happened between the last request to this endpoint and the time of this request. For example, consider this series of events:
1. A request to /clips (POST) is made at 06:00:00 and reports some clips that happened prior to 06:00:00.
2. Between 06:00:00 and 06:15:00, 12 clips occurred:
a. 8 clips for a coupon with ID 1111
b. 4 clips for a coupon with ID 2222
3. The next request to /clips (POST) is made at 06:15:00. This request should only include the 8 clips for 1111 and the 4 clips for 2222, not any that occurred before 06:00:00.
Each call to this endpoint accepts an array of “ClipData”. Each ClipData has both a CouponId and a ClipCount field. Using this schema, you can report all of your coupon clips in one request. Note that if you report a CouponId with a ClipCount of zero (0), this is considered an error by this API. Only coupons which have actually been clipped at least once in the interval since the last report should be included in each report.
The first call you should make when using this API is to the "Authenticate" endpoint (see the Swagger endpoint documentation for more details). This endpoint accepts your username and password as input parameters and provides you with a token int he response that you will use when making calls to all of the other endpoints. This token needs to be included in calls to other endpoints in an Authorization header:
The authentication/authorization token will remain valid for 24 hours. You can and should reuse this token as opposed to getting a fresh token before each other endpoint request. We recommend only refreshing your token after it has expired by using this process:
In the event of an API request failing, we ask that you do not simply resend requests continually until you get a working response. You should implement a retry system for all calls with a back-off timing interval. We recommend limiting retries to three with the following schedule: