Documentation

API Status: Affected

OffersImprove this page

Fidel Offers help you create and manage card-linked offers with various retailers – all in one place. The Fidel Offers API serves as a Transaction qualification engine for Fidel Offers. Developers can create Offers via the Fidel Offers API, which allows your application to create and update Offers, link and unlink Locations to the created Offers, activate and deactivate Offers on specific Cards and send the Offers for approval to a Brand. Brands and Merchants can interact with the Fidel Offers by using the Fidel CLO Dashboard.

Offer Lifecycle

Offers can be accessed via the Fidel Dashboard. They are grouped into four categories: Requests, Upcoming, Live and Expired.

Fidel Dashboard with Offers

Requests

The Offer startDate is set in the future, and/or there are no linked Locations.

Upcoming

The Offer has at least one Location linked, but the startDate is in the future. Offers in this category will automatically become "live" when the startDate is reached.

Live

The current date is between the Offer startDate and endDate. The Offers in this category are qualifying Transactions at the locations linked to them.

Expired

The current date is after the Offer endDate. The Offers in this category have stopped qualifying Transactions.

Creating an Offer

There are multiple options for creating a new Offer. You can create an Offer via the Fidel Dashboard, in the Offers section. Alternatively, Developers can use the Create Offer endpoint from the Offers API to create an Offer.

Create an Offer via Dashboard

Create Offer in Fidel Dashboard

Once you have created an Offer, it will enter the Offer Lifecycle in the Requests category.

Create an Offer via Offers API

Here's a cURL example of using the endpoint, with only the minimum required parameters:

123456789101112131415
curl -X POST https://api.fidel.uk/v1/offers \
  -H 'Content-Type: application/json' \
  -H 'Fidel-Key: <KEY>' \
  -d '{
        "countryCode": "GBR",
        "name":"20% Off Netflix Subscription",
        "publisherId":"3693ac7e-3e2b-432c-8c60-2b786453ca9b",
        "brandId":"f8bdb5e7-85c3-4acb-8a59-1b7e9218e412",
        "startDate":"2020-04-25T00:00:00",
        "type":{
          "name":"discount",
          "value":20
        }
      }'

Required Parameters

These are the minimum required parameters to create a new Offer:

  • brandId: Unique identifier for the Brand presenting the Offer.
  • countryCode: Country where the Offer will be available.
  • name: Name of your Offer.
  • publisherId: Unique identifier for you, the same as your Fidel accountId.
  • startDate: The start date for the Offer. The startDate time will be a local time relative to the Location where the Offer is active.
  • type: name: Type of the Offer. Valid names are "amount" and "discount".
  • type: value: Numeric value of the discount associated with the Offer.

Offers with the type amount will use the indicated country's currency and apply the value as the amount of the discount, for example, £20 Off. The discount type applies the value as a percentage discount, for example, 20% Off.

Optional Parameters

There are a range of optional parameters available, which influence how the Offer behaves on the Fidel platform. You can read more about the endpoint's full specification on our API Reference.

  • activation: An object, showing if the Offer needs activation or not. Default is { enabled: false }.
  • activation: enabled: Boolean showing if the Offer needs to be activated on Cards or not. If it's true, the activation object also has a qualifiedTransactionsLimit property. Please read the section below on Offer Activation before using this parameter.
  • activation: qualifiedTransactionsLimit: Number of Transactions to qualify for each Offer activation. Default is 1.
  • daysOfWeek: Array of numbers, with possible values from 0 to 6, to indicate the days of the week. 0 = Sunday, 1 = Monday, etc.
  • endDate: The date to automatically end the Offer. Same as startDate, the time will be a local time relative to the Location where the Offer was active.
  • funded: id: Unique identifier for the account that funds the Offer. For self-funded Offers, this is not required. In the test environment, all Offers are self-funded, so this will always be the same as your accountId.
  • funded: type: Type of Offer funding. Possible values are "merchant", "card-linking" and "affiliate". In the test environment, you can only create card-linked Offers, so the funding type will always be "card-linking".
  • maxTransactionAmount: Deprecated in favor of type: maxRewardAmount. For example, a 10% reward with a max transaction amount of £100 can't generate a reward larger than £10, even if the transaction amount is higher than £100. The new value for maxRewardAmount will be 10 since we want to limit the reward to £10.
  • minTransactionAmount: Minimum transaction amount to qualify for the offer. For example, if your offer is to save 25% on purchases over £50, then the Offer should have a minTransactionAmount of £50.
  • metadata: Object with your own metadata, will be returned on the Offer object.
  • returnPeriod: Number of days between when a Transaction was created and when a Transaction qualifies for the Offer. The qualified Transaction will have the offer.qualificationDate set to the creation date plus the number of days in the return period.
  • schemes: Array of schemes for which a Transaction qualifies for the Offer. Possible values are "amex", "mastercard" and "visa".
  • type: maxRewardAmount: Numeric value of the maximum amount to be awarded for the Offer. This only applies to discount type offers. For example, a 10% reward with a max reward amount of 10 can't generate a reward larger than £10, even if the transaction amount is higher than £100.

Multiple Offers on the same Brand and Location

Each Transaction can be rewarded only once. If there is more than one Offer for the same Brand in the same Location for which a Transaction qualifies, the Fidel API platform has to select one of them which will provide the reward.

The platform uses the following rules to select the Offer that will reward the cardholder:

  1. In case both Offers generate different cashback values, the platform selects and qualifies the most valuable offer;

  2. In case both Offers generate the same cashback values, the platform selects and qualifies the most recent offer.

Example:

Let's suppose the following offers are on the same brand and cardholder made a transaction of £100 at a brand’s location.

Offer 15 % Off:Offer £50 Off:
name: "discount"name: "amount"
value: 15value: 50

Applying the stacking rules, the above transaction will qualify for "Offer £50 Off" according to the first rule.

Linking Locations to Offers

Before an Offer goes live and starts qualifying transactions, you will need to link Locations to the Offer. Developers can use the Link Location to Offer API endpoint to link any Location to an Offer. Similarly, the Fidel API has an endpoint to unlink a Location from an Offer.

Here's a cURL example of using the endpoint, with two path parameters, for the offerId and locationId:

12345
curl -X POST \
  https://api.fidel.uk/v1/offers/feb9af3c-9b4e-49df-bb8f-13ae4ad8cd22/locations/1af3b7a0-4bfd-4b5e-a285-fab1c8a8421d \
  -H 'Content-Type: application/json' \
  -H 'Fidel-Key: <KEY>'

Linking All Brand Locations to an Offer

Developers can use the Link All Brand Locations to Offer API endpoint to link all Location from a Brand to an Offer.

Here's a cURL example of using the endpoint, with the two required path parameters, for the offerId and programId:

12345
curl -X POST \
  https://api.fidel.uk/v1/offers/feb9af3c-9b4e-49df-bb8f-13ae4ad8cd22/programs/0228b979-6f7c-4238-a309-40f9d6efd3ea/locations \
  -H 'Content-Type: application/json' \
  -H 'Fidel-Key: <KEY>'

Linking Offers in the Dashboard

When you create an Offer in the Fidel Dashboard, the second step of the creation dialogue allows you to link Locations to the newly created Offer.

Link Locations in Offer Creation

If you need to link more Locations after you've created an Offer, the Locations list in the Dashboard has a menu button next to each Location, which opens a contextual menu. Selecting 'Link to offer' in the context menu will open a drawer that lets you select a possible Offer to link.

Link to offer in Fidel Dashboard

Alternatively, you can edit an Offer in the Fidel Dashboard, which will allow you to link more Locations in the second step of the Offer drawer.

Edit Offer Link Locations

Offers with Activation

Offers with activation require an Offer to be activated on a Card before they can go through the qualification process. Developers can use the Offers API to specify an Offer requires activation. When creating an Offer, the activation object should have the enabled: true property and a qualifiedTransactionsLimit property higher or equal to 1. The qualifiedTransactionsLimit property specifies how many Transactions will be qualified for each Offer activation. Here's a cURL example:

12345678910111213141516171819
curl -X POST https://api.fidel.uk/v1/offers \
  -H 'Content-Type: application/json' \
  -H 'Fidel-Key: <KEY>' \
  -d '{
        "countryCode": "GBR",
        "name":"20% Off Netflix Subscription",
        "publisherId":"3693ac7e-3e2b-432c-8c60-2b786453ca9b",
        "brandId":"f8bdb5e7-85c3-4acb-8a59-1b7e9218e412",
        "startDate":"2020-04-25T00:00:00",
        "type":{
          "name":"discount",
          "value":20
        },
        "activation":{
          "enabled":true,
          "qualifiedTransactionsLimit":1
        }
      }'

Offers need to be activated on Cards before the purchase to receive and qualify Transactions for Offers with activation. Developers can do that by using the Activate Offer on Card API endpoint as follows:

12345
curl -X POST \
  https://api.fidel.uk/v1/offers/:offerId/cards/:cardId \
  -H 'Content-Type: application/json' \
  -H 'Fidel-Key: <KEY>'

After an Offer is activated on a Card, it will qualify the number of Transactions specified by the qualifiedTransactionsLimit value. After the limit of Transactions is qualified, the Offer is automatically deactivated from the Card. If developers need to deactivate an Offer from the Card for any reason before that event, they can use the Deactivate Offer on Card API endpoint.

Note that when you link Locations to an Offer with activation, you will only receive Transactions from Cards where the Offer has been activated on. To receive all Transactions from all Cards, you will need to disable the Offer activation with activation: { enabled: false, qualifiedTransactionsLimit: 1 } or unlink the Locations from the Offer.

It is not possible to run an activation offer and a non-activation offer at the same time for the same brand. Should you wish to run two offers at the same time for the same brand, they must both be activation offers or both be non-activation offers. If you are running two offers at once, only one transaction webhook will be sent for whichever offer has the highest award.

Test and Live environments
It is important to note that when testing Offers with activation in the test environmentm all test transactions created will be visible for testing purposes. In the live environment only Transactions for activated Offers on Cards will be received and qualified.

Offers with Activation in the Dashboard

You can create Offers with activation in the Fidel Dashboard as well. When creating an Offer, check the "Enable offer activation" checkbox. That will reveal a "1" transactions field, which you can use to change the number for the qualified transactions limit.

Create Offer with Activation

To activate an Offer on a Card using the Fidel Dashboard, you'll want to go to the Cards list. Each Card has a menu button next to them, which opens a contextual menu. Selecting 'Activate offer' in the context menu will open a drawer that lets you select a possible Offer to activate on the Card.

Activate offer on Card in Fidel Dashboard

Transaction Qualification

When an Offer is Live, each transaction made by an enrolled Card will be analysed against the Offer parameters and will be qualified against the Offer. If the Offer has a return period, transactions will only qualify for the Offer after the return period has passed.

In both cases, an offer object is appended to the original Transaction object containing the qualification result data. In case the Transaction qualifies, cashback and performanceFee properties are calculated and the qualified property is set to true. If the qualified Transaction was for an Offer with a return period, the offer.qualificationDate is set to the Transaction creation date plus the number of days in the Offer return period. If the Transaction does not qualify, cashback and performanceFee properties will have a 0 value. The qualified property will be set to false and a message explaining why the Offer did not qualify will be set in the message property. If a Transaction does not qualify for multiple Offers, the rejection message is for the most recent Offer. You can see examples for qualified and non-qualified Transactions below.

qualified-transaction.json
1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162
{
  "id": "7fdfd5d8-9589-402f-8477-4a727ad239a2",
  "accountId": "4ed4b62b-aa4c-43a1-8064-da6d1368e17a",
  "programId": "6e38aa0c-b7ef-46bd-b1bd-c07c648d9cba",
  "datetime": "2020-04-21T19:12:01",
  "created": "2020-04-21T19:12:01.744Z",
  "updated": "2020-04-21T19:12:01.744Z",
  "auth": true,
  "cardPresent": false,
  "cleared": false,
  "amount": 5,
  "currency": "USD",
  "wallet": null,
  "card": {
    "id": "bc538b71-31c5-4699-840a-6d4a08693314",
    "firstNumbers": "555500",
    "lastNumbers": "5001",
    "scheme": "visa",
    "metadata": {
      "customKey1": "customValue1",
      "customKey2": "customValue2"
    }
  },
  "brand": {
    "id": "9d136f2e-df99-4a08-a0a5-3bc1534b7db9",
    "name": "Starbucks",
    "logoUrl": null
  },
  "location": {
    "id": "7a916fbd-70a0-462f-8dbc-bd7dbfbea160",
    "address": "5th Avenue",
    "city": "New York",
    "postcode": "120000",
    "countryCode": "USA",
    "timezone": "America/New_York",
    "geolocation": {
      "latitude": 51.5152346,
      "longitude": -0.1310718
    },
    "metadata": {
      "customKey1": "customValue1",
      "customKey2": "customValue2"
    }
  },
  "offer": {
    "id": "7e55eeae-99d6-4daf-b8c4-ac9ca660e964",
    "cashback": 20,
    "message": [],
    "performanceFee": 3.2,
    "qualified": true,
    "qualificationDate": null
  },
  "identifiers": {
    "MID": "123456789",
    "mastercardTransactionSequenceNumber": "0000000000000",
    "mastercardRefNumber": "AABBCCDDE",
    "amexApprovalCode": "AA00BB",
    "visaAuthCode": "000000",
    "mastercardAuthCode": null
  }
}

non-qualified-transaction.json
123456789101112131415
{
  "...": "...",
  "updated": "2020-04-19T12:12:00.000Z",
  "offer": {
    "id": "7e55efae-99d6-4daf-b8c4-ac9ca660e864",
    "cashback": 0,
    "performanceFee": 0,
    "qualified": false,
    "qualificationDate": null,
    "message": [
      "Transaction amount of 5 USD is lower than the offer's minimum transaction amount of 10 USD"
    ]
  }
}

Offer Object

The Offers API's central piece of data is the Fidel Offer object, which holds all the details about a card-linked Offer. The card-linked Offer has a set of parameters used to qualify any Card Transaction made at a participating Brand's linked Location.

The Offer object looks similar to the following and will be returned by the API in a multitude of situations. Transaction objects will also have a smaller version of the object inside, making it easier to retrieve the full Offer object if necessary.

offer.json
12345678910111213141516171819202122232425262728293031323334353637383940414243444546
{
  "id": "feb9af3c-9b4e-49df-bb8f-13ae4ad8cd22",
  "accepted": true,
  "activation": {
    "enabled": true,
    "qualifiedTransactionsLimit": 1
  },
  "additionalTerms": null,
  "brandId": "f8bdb5e7-85c3-4acb-8a59-1b7e9218e412",
  "brandName": "API Reference",
  "brandLogoURL": "https://example.com/logo.png",
  "countryCode": "GBR",
  "created": "2020-07-29T13:45:36.191Z",
  "currency": "GBP",
  "daysOfWeek": [0, 1, 2, 3, 4, 5, 6],
  "endDate": null,
  "feeSplit": 70,
  "funded": {
    "id": "3693ac7e-3e2b-432c-8c60-2b786453ca9b",
    "type": "card-linking"
  },
  "live": true,
  "locationsTotal": 240,
  "maxTransactionAmount": 0,
  "minTransactionAmount": 0,
  "metadata": null,
  "name": "£5 Off Netflix Every Month",
  "origin": {
    "id": "3693ac7e-3e2b-432c-8c60-2b786453ca9b",
    "type": "card-linking"
  },
  "priority": 1,
  "publisherId": "3693ac7e-3e2b-432c-8c60-2b786453ca9b",
  "returnPeriod": 15,
  "schemes": ["amex", "mastercard", "visa"],
  "startDate": "2020-06-30T00:00:00",
  "supplier": null,
  "type": {
    "name": "discount",
    "maxRewardAmount": 10,
    "value": 5
  },
  "status": "live",
  "updated": "2020-08-22T14:47:37.479Z"
}

Parameters

idstring
Unique identifier for the object.
acceptedboolean
Whether the Offer was accepted by the Brand. To send the Offer to a Brand for funding, see the Send Offer to Brand API endpoint.
activationobject
Has an enabled boolean property, showing if the Offer needs activation or not. If the enabled flag is set to true, the activation object also has a qualifiedTransactionsLimit property, specifying the number of transactions to qualify for each Offer activation. You can read more about Offers with Activation below.
additionalTermsstring
Support for additional Terms & Conditions related to the Offer. null by default.
brandIdstring
Unique identifier of the associated Brand.
brandNamestring
Name of the associated Brand.
brandLogoURLstring
Logo URL of the associated Brand. null by default.
countryCodestring
ISO 3166-1 alpha-3 country code for the Country where the Offer is active.
createddate
ISO 8601 date and time in UTC representing the creation date for the Offer object.
currencystring
ISO 4217 currency code based on the countryCode value.
daysOfWeekarray: number
Array of numbers between 0 and 6 representing the days of the week for which the Offer is active. Starting with Sunday.
endDatedate
Date and time, in the YYYY-MM-DDThh:mm:ss format, for when the Offer expires. Note: Time is local to the Location. Defaluts to null for Offers that do not expire.
feeSplitnumber
Explains the amount to be awarded to the publisher (Fidel customer) as their performance fee. Offers with the amount type will use the indicated country’s currency and apply the value as the amount, for example, £2. Offers with the discount type applies the value as a percentage, for example, 2% of the transaction value.
fundedobject
Contains an id property, with the unique identifier for the account that is funding the Offer. Also contains a string type property, for the type of account that is funding the Offer. The type can have one of the values "merchant" | "card-linking" | "affiliate".
liveboolean
Whether the Offer should be created in the live or test Fidel environment.
locationsTotalnumber
Total number of Locations linked to the Offer.
maxTransactionAmountnumber
Maximum transaction amount generating a proportional reward.
minTransactionAmountnumber
Minimum amount needed for a Transaction to qualify for the Offer.
namestring
Name of the Offer.
metadataobject
Metadata to be associated with the Offer. Defaults to null.
originobject
Contains an id property, with the unique identifier for the account that created the Offer. Also contains a string type property, for the type of account that created the Offer. The type can have one of the values "merchant" | "card-linking" | "affiliate".
prioritynumber
Not in use. Its value is always 1.
publisherIdstring
Unique identifier of the Publisher. Refers to accountId.
returnPeriodnumber
Number of days before a Transaction qualifies for the Offer.
schemesarray: string
Card Schemes for which the Offer is valid. Possible values in the array are visa, mastercard and amex.
startDatedate
Date and time, in the YYYY-MM-DDThh:mm:ss format, for when the Offer is activated and starts qualifying transactions.
statusstring
Offer status corresponding to the state in the Offer Lifecycle. Can be one of requests, upcoming, live or expired.
supplierobject
Contains an id property, with the unique identifier for the account that supplies the Offer. Also contains a string type property, for the type of account that supplies the Offer. The type can have one of the values "merchant" | "card-linking" | "affiliate". Defaluts to null.
typeobject
Represents the type of Offer: a fixed amount or a percentage of the original transaction The name property can have one of the following two values: amount anddiscount. The value property has either the fixed amount of currency to be rewarded or the percentage value, depending on the Offer type. The maxRewardAmount property has a maximum fixed amount of currency to be rewarded for percentage typed Offers. maxRewardAmount only applies to discount Offers, and will be null for amount Offers.
updateddate
ISO 8601 date and time in UTC representing the last time the Offer object was updated.

Deleting Offers

You can delete offers in the Fidel API Dashboard, or using the API's Delete Offer endpoint.

12345
curl -X DELETE \
  https://api.fidel.uk/v1/offers/ec80c3a1-0899-4e10-abdf-2dfb699b509c \
  -H 'Content-Type: application/json' \
  -H 'Fidel-Key: sk_test_50ea90b6-2a3b-4a56-814d-1bc592ba4d63'

API Reference

If you're looking to find out more about our Offers API and how to use it with your application, please visit the Fidel API Reference.