How to create a card-linked offer
Tags: developers, blogs, cardlinking, tech
Published: 2020-06-22 08:43:41

---
title: How to create a card-linked offer
published: true
date: 2020-06-17 13:28:18 UTC
tags: Developers,Blogs,Cardlinking,Tech
canonical_url: http://blog.fidel.uk/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](https://dashboard.fidel.uk/). 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](https://fidel.uk/docs/getting-started)).

### 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.](https://reference.fidel.uk/reference#create-offer)  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](https://fidel.uk/docs/offers/#offer-object). 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](https://reference.fidel.uk/reference#create-offer).

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 the[Link Location to Offer](https://reference.fidel.uk/reference#add-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 the[List Locations By Offer](https://reference.fidel.uk/reference#list-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 the[Fidel Webhook Glitch demo](https://fuschia-savory-mangosteen.glitch.me/), 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.

<!--kg-card-begin: html-->
[Join the developer community](https://community.fidel.uk/)
<!--kg-card-end: html-->