SFTP Option

Abstract

This document describes the standardized process for partners to submit offer data files using SFTP for ingestion. Partners must upload daily JSON files named in the format <Partner_Name>OffersCCYYMMDD.json, containing all current offers and their metadata. Each file must include a header record and classify offers by status—NEW, UPDATED, UPSERT, NO-CHANGE, or DELETED—using the offerStatus field.

The file replaces any previous file with the same name, and uploads are only required when there are new, updated, or deleted offers. The system continues using the last file if no updates are provided. Consistency in offer identifiers (offerId) across uploads is essential, and files must be correctly formatted in JSON to ensure successful processing.

How It Works

• Standardized schema format for getting the Offers file for ingestion from the Partner.
• Partners use SFTP URL to upload file.

Recommendations on how to call

• File Type: JavaScript Object Notation (JSON)
• File Name: <Partner_Name>OffersCCYYMMDD.json
  • <Partner_Name> → Your unique identifier as a partner.
  • CCYYMMDD → The date of file creation in 4-digit year, 2-digit month, and 2-digit day format.
• File Frequency: Once a day (if there are new/updated/deleted offer)
• File Upload Requirements
  • Partners must provide a full dump of all offers, including corresponding metadata, with each file upload
• File Features
  • File must contain the header record as mentioned above
  • All Active Offers will appear in the file broken down by status – NEW/UPDATED/UPSERT/NO-CHANGE
  • All Deleted Offers for the day will appear under the file under status – DELETED
  • An Updated Offer Record can have one or more updates to its attributes.
• File Overwrite Policy
  • If a file with the same name already exists, it will be replaced by the newly uploaded file.
• When Is File Upload Required?
  • If there are new, updated, or deleted offers, a new file must be uploaded.
  • If there are no changes (i.e., no offers were added, updated, or removed), file upload is not required.
    • CDLX will continue using the previously uploaded offer list until a new file is provided.
• Offer Status Field
  • Every offer entry in the JSON file must include a "offerStatus" field to indicate changes compared to the previously uploaded file.
  • The "offerStatus" field can have one of the following values:
    • NEW - A new offer has been added.
    • UPDATED - An existing offer information has changed.
    • UPSERT - The offer is new or updated.
    • DELETED - The offer should be removed from the list.
    • NO-CHANGE - The offer data remains the same as in the previous upload.
• Additional Guidelines
  • Ensure files are properly formatted in JSON to avoid processing errors.
  • Retain the same offer identifiers (offerId) across file uploads for consistency in tracking changes.

Sample File Content

{
    "headerRecord":
    {
        "fileDescription": "Offers",
        "fileCreationDate": "2025-01-27",
        "merchantRecordCount": 2
    },
    "offerRecords":
    [
        {
            "offerId": "offer_101",
            "merchantId": "merchant_101",
            "offerName": "Test merchant 101",
            "assets":
            {
                "logo":
                {
                    "type": "IMAGE",
                    "value":
                    {
                        "large":
                        {
                            "url": "htttps://google.com"
                        }
                    }
                },
                "largeRectangle":
                {
                    "type": "IMAGE",
                    "value":
                    {
                        "large":
                        {
                            "url": "htttps://google.com"
                        }
                    }
                }
            }
        },
        {
            "offerId": "offer_102",
            "merchantId": "merchant_102",
            "offerName": "Test merchant 102",
            "assets":
            {
                "logo":
                {
                    "type": "IMAGE",
                    "value":
                    {
                        "large":
                        {
                            "content": "<BASE_64_ENCODED_STRING>"
                        }
                    }
                },
                "largeRectangle":
                {
                    "type": "IMAGE",
                    "value":
                    {
                        "large":
                        {
                            "content": "<BASE_64_ENCODED_STRING>"
                        }
                    }
                }
            }
        }
    ]
}