Fidel.ukFidel - Home

Offers

The Offer object holds the details about a card linked offer. Offers can be created by developers using the Offer API or by Brands/Merchants using the CLO dashboard at clo.fidel.uk. A card linked offer specifies a set of parameters that will be used to qualify a card transaction made at a participating Brand’s online or offline store.

Offer object

offer.json

{
  "id": "49b407ef-508a-432b-900c-a04e5e6ac86c",
  "activation": false,
  "additionalTerms": null,
  "brandId": "e4928475-6a39-41e6-8484-951202d43de9",
  "brandName": "Starbucks",
  "brandLogoURL": "https://starbucks.com/logo.png",
  "countryCode": "USA",
  "created": "2020-04-18T12:12:00.000Z",
  "currency": "USD",
  "daysOfWeek": [0,1,2,3,4,5,6],
  "endDate": "2020-06-20T13:13:00",
  "feeSplit": 70,
  "funded": {
    "id": "d346d574-d5c2-4a0e-8e02-ffd713fd1a9d",
    "type": "card-linking"
  },
  "live": true,
  "locationsTotal": 240,
  "minTransactionAmount": 10,
  "maxTransactionAmount": 100,
  "name": "20% Off Everything",
  "priority": 1,
  "publisherId": "d346d574-d5c2-4a0e-8e02-ffd713fd1a9d",
  "returnPeriod": 15,
  "schemes": [
    "amex",
    "mastercard",
    "visa"
  ],
  "startDate": "2020-04-20T00:00:00",
  "type": {
    "name": "discount",
    "value": 20
  },
  "updated": "2020-04-18T12:12:00.000Z"
}

Parameters

id string
Unique identifier for the object.
activation boolean
If set to true cards need to be activated before the purchase for the transaction to be tracked. Only one transaction is tracked and qualified for each card activation.
additionalTerms string
Additional terms related to the offer.
brandId string
Id of the Brand.
brandName string
Name of the Brand.
brandLogoURL string
Logo URL of the Brand. null if no URL is provided.
countryCode string
ISO 3166-1 alpha-3 country code where the offer is active.
created date
ISO 8601 date and time in UTC representing when the object was created.
currency string
ISO 4217 currency code based on country code value.
daysOfWeek array: number
Array of numbers between 0 and 6 representing the days of the week. Starting on Sunday.
endDate date
Date and time, in format YYYY-MM-DDThh:mm:ss, when the offer will complete.
feeSplit number
Percentage of the performance fee to be charged by Fidel to the Brand.
funded object
Id of the account that is funding the offer. type is the type of account that is funding the offer and can have one of the following values: {merchant, card-linking, affiliate}
live boolean
Whether the offer should be created in live or test environment.
locationsTotal number
Total number of locations linked to the offer.
minTransactionAmount number
Minimum transaction amount to qualify for offer.
name string
Name of the offer.
priority number
Number starting in 1, representing stacking priority for publisher. By default, publisher that invites Brand gets top priority = 1.
publisherId string
Id of the publisher. Refers to accountId.
returnPeriod number
Number of days before a transaction qualifies for the offer.
schemes array: string
Schemes where the offer is valid. Possible values are visa, mastercard and amex.
startDate date
Date and time, in format YYYY-MM-DDThh:mm:ss, when the offer gets activated and starts qualifying transactions.
type object
An offer can be a fixed amount off or a percentage discount of the transactions amount. type: {name: string, value: number}. The name property can have one of the following two values: amount and discount. The value property saves the fixed amount of currency to be rewarded or the percentage value in case of a discount offer.
updated date
ISO 8601 date and time in UTC representing when the object was last updated.

Create Offer

To create an offer you can use the Create Offer API endpoint or the dashboard and specify your offer parameters.

See below an example on how to create an offer using the Create Offer endpoint:

curl -X POST \
  https://api.fidel.uk/v1/offers \
  -H 'content-type: application/json' \
  -H 'fidel-key: sk_live_152c2c3c-3bc1-49af-84e2-82646f303c13' \
  -d '{
        "countryCode": "USA",
        "name":"20% Off Everything",
        "brandId":"585dca42-2c77-4007-8429-9496782fd16a",
        "publisherId":"4ed4b62b-aa4c-43a1-8064-nb7d1368e17a",
        "startDate":"2020-04-20T12:13:13",
        "type":{
          "name":"discount",
          "value":20
         }
       }'

As required parameters, you need to set an offer name, your accountId as the publisherId, the brandId, a startDate, the type of offer between amount or discount, an offer value, and the countryCode where the offer will be available. The value is a percentage if the offer type is discount or a fixed amount in the local currency of the countryCode specified.

Check out the Offer API Reference for more detailed documentation about available Offer API endpoints.


Offer Lifecycle

An offer qualifies transactions depending on a combination of three properties: startDate, endDate and locationsTotal. On the dashboard offers are grouped between pending, all-set, live and expired.

If the offer is labeled as pending it means that the startDate is in the future or it has no linked locations. When an offer has at least one location linked to it and the startDate is set in the future, the offer is placed in the all-set group. An offer is live when today's date is between the offer's startDate and endDate and locationsTotal is greater than 0. An offer will be bound to the time zone of linked locations, startDate and endDate will correspond to the locations’ local time.

Pending

Offer startDate is set in the future. Offer will start qualifying when transactions are made at locations linked to the offer after the startDate.

Live

Current day is between startDate and endDate and offer is qualifying transactions at the locations linked to it.

Expired

Current day is after the endDate. The offer has stopped qualifying transactions.


Qualification

When an offer is live, each transaction made by a linked card on a location linked to the offer will be analysed against the offer parameters and can qualify or not qualify for the offer.

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 amounts are calculated and the qualified property is set to true. If the transactions does not qualify, cashback and performanceFee amounts will be 0, the qualified property set to null and a message explaining why the offer did not qualify is set in the message property. You can see examples for qualified and non-qualified transactions below.

qualified-transaction.json

{
  "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,
  "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"
  }
}

non-qualified-transaction.json

{
  "...": "...",
  "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"
    ]
  }
}

Activation

Offer activation allows developers to require that offers are activated on cards in order to qualify for a reward. This feature is part of the Offers API and can be used by creating offers that require activation with activation: true. This can be done using the Create Offer API endpoint or using the dashboard.

To receive and qualify transactions for offers with activation, offers need to be activated on cards before the purchase. That is done by using the Activate Offer on Card API endpoint as follows:

curl -X POST \
  https://api.fidel.uk/v1/offers/:offerId/cards/:cardId \
  -H 'content-type: application/json' \
  -H 'fidel-key: your-secret-key'

You can also activate an offer on a card using the dashboard by clicking on a card’s options menu, click ‘Activate offer on card’ and select the offer to activate.

When an offer is activated on a card, the next transaction at any of the offer locations will be tracked and qualified based on the offer rules. After the first transaction is qualified for a reward the offer is automatically deactivated from the card.

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 disable the offer activation with activation: false or unlink the locations from the offer.

Test and live environments
It is important to note that when testing offers with activation in test environment all test transactions created will be visible for testing purposes as opposed to live environment where only transactions for activated offers on cards will be received and qualified.