Please note

The following is a guide only and not suggested to be best practice or the way you should implement a connection to the Seamless Rewards API. It purely provides an example of ways the API could be used. How you implement/integrate it into your own systems is purely up to you.

Step 1 - Authenticate

Assuming you've been issued with you credentials (a clientId and a clientSecret) you are able to obtain a bearer token by making a POST request. For details on this please see Authorization

Step 2 - Retrieve all merchants, locations and offers

This is likely a step you'll only perform once, unless you want to complete refresh the content from time to time. In our example we did this by implementing a loop and calling the List Merchants and providing 5 key parameters:

• isFetchOffer: true
• isFetchLocation: true
• sortBy: ModifiedOn
• noOfRecords: 50
• page: [page]
  By looping through the results until the number of records returned is less than the page size (50 in the example) we are able to pull down the complete set of data.

As each of these records are received we stored it locally in 3 different tables,

• merchants (linked to offers and locations)
• locations (linked to related merchant and related offers)
• offers (linked to related merchant and related locations)

In each case there are references/links between the tables allowing us to list either by location (ordered by distance from the user) or by offer (sorted by offer value in descending order so a user could see the highest offer values first).

The merchant data contains both ABNs and MIDS which can be used to match with existing (your own) merchants. In our case we also stored the field "merchantId" which is the Seamless Redemption internal unique reference.

Both merchants and offers have categories. merchantCategory is a high-level category whereas categoryName could be considered a sub-category. categoryName is intended to be used as tags by which a search engine can narrow down the results. A merchant may have only one category eg Dining, whereas the offers may have multiple categoryNames eg. ‘Bistro’ and ‘French’.
See this page for a list of the values for merchantCategory and categoryName.
Our APIs expose an ID for the merchantCategory instead of the value. This is to facilitate mapping to an appropriate category in your system.

Step 3 - Maintain merchants, locations and offers

In order to keep all the Seamless Rewards data in sync with the local tables, we do a daily fetch of updates.
This is done by using exactly the same request as was used in Step 2, with the same set of parameters. The only difference is that we exit the loop once we get to data where the merchant "modifiedOn" field was more than 2 days ago. Even though we do the request every single day, we filter 2 days worth of data to provide an overlap to ensure we don't miss any changes.

For each of these records we then update our local tables to reflect these changes (for merchants, locations relating to those merchants as well as offers relating to those merchants)

While location changes cause the merchant record's "modifiedOn" field to be updated, offer data does not. This means that during our daily update, we do need to also make the same call to retrieve offers that have been updated using the List Offers.

Step 4 - Add Transactions

Now we have all our merchant/offer and location data up to date at all times, we are able to process transactions.
In the Seamless Rewards implementation there may be a number of offers linked to a single MID. We leave it to you to decide (or allow the customer to decide) which offer you want to claim.

Note on offer changes

In our system we do not allow offer values to to be changed. This is to ensure we can always provide at least 7 days advance notice on any offer changes. As such an offer change is implemented as the expiry date being set to 7 days from the date of change and a new offer created in parallel. This means that in many cases there may be 2 offers and you are able to choose the highest value out of the 2.

To notify us of a transaction that occurred, perform a POST request to Add Transactions

Step 5 - Reconciliation

The Seamless Rewards API allows you to retrieve a list of Recipient Created Tax Invoices created on your behalf to match the transactions we processed. Each of these also provide a list of transactions that were included in those invoices. In our example we used these calls to cross reference to the transactions we processed and stored locally. Once matched we marked the transaction (and invoice) as reconciled. This allows us to monitor any transactions that are yet to be paid out on.