How to create a card-linked offer

Fidel does more than just allow you to spot when transactions are made. We also enable you to create card-linked offers that you can promote to your customer database. These offers allow you to drive value to your customers, and get data in real-time when offers are redeemed.

You can be targeted with your offers, too. Want to give 10% off all purchases made in your Soho store on Mondays? We’ve got you. If you want to offer many different tiers of offers, Fidel gives you the flexibility to apply different discounts or savings to the purchase based on the transaction value. And because data from transactions is delivered in real-time, you can improve engagement with your customers by communicating with them immediately after the offer is redeemed.

Let’s walk through the process for creating an offer. In this tutorial, we’ll use the Fidel API endpoints with curl to create, activate and evaluate an offer. The same can be done in the Fidel Dashboard. In this post, we’ll assume that you already have a Fidel Developer account, and that you have an active card-linking programme running (to learn how to create a card linking program, please follow the tutorial in our documentation).

Creating the Offer

Each Offer is connected to a Brand in your card-linking scheme. Once the Offer is created, it is tied to specific Locations, and all transactions for that Brand/Location combination are evaluated against the Offer to see if they qualify.

To create an Offer, we use the Create Offer endpoint. Here is a minimal solution for an Offer:

curl -X POST https://api.fidel.uk/v1/offers \
    -H 'content-type: application/json' \
    -H 'fidel-key: sk_test_KEY' \
    -d '{
    "countryCode": "IRL",
    "name":"20% Off Everything",
    "brandId":"0b7b83a3-ccb3-4854-804a-90e5d951d1eb",
    "publisherId":"fec57ce7-d161-4c8f-8da0-1ebf841f4739",
    "startDate":"2020-05-20",
    "type":{ "name":"discount", "value":20 }
}'

What we are telling the API is to create a “20% off Everything” Offer in Ireland that starts on 20 May 2020 for the selected Brand. The publisherId is your Fidel Account ID. This comes back with a success message and a JSON output describing your Offer. A sample JSON output can be seen in the docs. In this case, all we need to know is the offerId:

"id": "484ac266-b7a6-4a3e-b9d8-08ba4037a3ec",

We could optionally add an endDate, days of the week that the Offer is valid, and min/max transaction values for the Offer. You can read about all the optional parameters in the API specification.

This Offer is not yet live, and if you go to the dashboard, you’ll see that it is in a pending status. For an Offer to be live, the current date must be between the start and end dates (in this case after 20 May 2020) and have at least one Location associated with it.

Adding Locations to the Offer

Since it is after 20 May, the only requirement to activate this Offer is to add a Location. Locations may be added using theLink Location to Offer endpoint.

The Offer I created earlier in this post has:

"id": "484ac266-b7a6-4a3e-b9d8-08ba4037a3ec",

And I’d like to add a Location with ID:

"id": "1a500096-9e74-414c-b6f0-edcfc0ef991d",

These are placed in the URL after the /offers/ and /locations/ parameters:

curl -X POST https://api.fidel.uk/v1/offers/\
484ac266-b7a6-4a3e-b9d8-08ba4037a3ec/\
locations/1a500096-9e74-414c-b6f0-edcfc0ef991d \
    -H 'content-type: application/json' \
    -H 'fidel-key: sk_test_KEY' \
    -d ''

This API call returns a 200, indicating that the Location has been added to the Offer.

Listing Locations in your Offer

Once you have added a number of Locations in your Offer, the offers API tells you how many Locations are affiliated with the Offer, but no further information. If you want to get detailed information about each Location included in the Offer, use theList Locations By Offer API.

curl -X GET https://api.fidel.uk/v1/offers/\
b6a559e0-c1c3-430d-b681-616aaec4e0c3/locations \
    -H 'Content-Type: application/json' \
    -H 'Fidel-Key: sk_test_KEY’'

This will return a JSON list of all the Locations included in the Offer, with addresses, Geolocations, merchantIDs, etc. Now you can easily audit the Locations, build a map, etc. with the Locations in the Offer.

Live Offer

Now that the Offer has a Location, and the startDate is in the past, this Offer is live for users. It will have moved on the Dashboard from pending to live.

We can now send transactions to this Location and check to see if the Offer is applied. This requires using the Transaction.auth.qualified webhook.

NOTE: the transaction.auth webhook does not contain Offer qualification data.

When a transaction occurs at the Location with the live Offer, the transaction.auth.qualified webhook returns the status of the Offer. In this case, a purchase of €10 should receive €2 back.

Using a modification of theFidel Webhook Glitch demo, we see the JSON response for the qualified Offer:

offer: {
    qualified: true,
    id: '484ac266-b7a6-4a3e-b9d8-08ba4037a3ec',
    message: [],
    qualificationDate: null,
    cashback: 2,
    performanceFee: 0.32
},

Conclusion

So, we’ve completed our goal: creating an Offer that can be identified and reported in real-time using Fidel’s offers. How are you planning to use Fidel’s offers with your existing card-linking strategy? Please let us know in our Developer Community.

Join the developer community