There are some situations in which a retailer wishes to use AIR to issue codes that belong to a third party. For example, a retailer might have obtained 100,000 codes from Amazon that give a 10% discount when entered into the Amazon checkout. Those codes, however, are issued to a customer based on actions in AIR.

To facilitate this, AIR has a Third-Party Code ingestion process that takes a file of codes and ingests them against a campaign in AIR. This way, the codes can be issued via the AIR issuance mechanics and delivered to the customer for use at a third-party retailer as a reward for their loyalty interactions.

Campaign Setup

Before an ingestion can be completed, a campaign in AIR is required which is configured to generate tokens and has a "Third Party Codes" code provider linked with it and a Token Format which matches the format of the incoming codes from the third party.

Once the campaign is created, a file of the codes is required that meets the configuration below.

File Format

The table below outlines the file structure required for this process

Name	Mandatory	Description	Example
token	Y	The token value to be ingested against the campaign below.	ABC1234560
campaignId	Y	The ID of the campaign against which the codes should be ingested	58762417

File Encoding

All files must be encoded with Linux line endings rather than Windows.

Field Encapsulation and Escaping

It is advised to wrap all fields in double quotes to avoid any issues with commas inside fields (E.g. the transaction description field). Because of this, if you want to use any double quotes inside the fields, they need to be escaped themselves. This can be done by adding a \ character before the " character.

File Naming

There is no restriction on the file name setup for this job other than a file extension of .csv. It is advised however to include some data points in the file name for easy identification and troubleshooting. For example, a file name structure similar to this is recommended: YYYYMMDDHHMMSS_third_party_codes.csv

This format will mean files are ordered in date/time order when listed in an SFTP client, it's clear the file is a points adjustment file. An element of random could be added to the file name if required.

Example File

The below example shows a very simple file specifying the mandatory fields and one of the optional fields.

token,campaignId
ABC1234560,1234567890
ABC1234561,1234567890
ABC1234562,1234567890

SFTP Folder Setup

If this ingestion is being triggered via an SFTP folder setup (manual runs by the EagleEye Operations team is possible however frequent runs of this job should be scheduled to run on an agreed time frame. Please contact your EagleEye team to help with this.

For files getting delivered to an SFTP location, the folder paths should match the below:

Your Eagle Eye onboarding team will get the sftp folders set up for you during the onboarding process. The folders created for this job will be as below:

/third-party-codes/outbound/
/third-party-codes/inbound/
/third-party-codes/processed/
/third-party-codes/error/

To ingest a file, it needs to be placed in the inbound folder. The first thing the job does is move this file into the processed directory before downloading the file. This is to prevent any duplicate processing or race conditions as the same file name can not be processed more than once.

When the job is completed, an output file will be placed in the outbound directory. This file contains all the same fields as the input file but with three extra columns, a success field (Y/N), an errorCode field holding the errorCode returned from the API request and errorMessage that holds the error message from the API. If there is any error in ingesting a single record, the success column will have a value of N and the errorCode and errorMessage columns will contain the details of why the record has failed.

Example output file

The output file from this ingestion will only contain the records in the ingestion that have caused an error.

The output file is the same as the input but with an additional column stating the error that has occurred.

token,campaignId,output
1234567890,101219938,"failed ingesting row #4 - token duplicate"
6549873210,1,"failed ingesting row #5 - bad campaign config"