Frequently Asked Questions

What are the primary components of the Demand Partner and CDLX integration?
The integration consists of four main components: the Merchant Ingestion API for managing merchant data, the Offer Ingestion API for managing offer details, the Redemption Feed which provides transaction redemption data from CDLX to the partner, and the Aggregate Reporting API enabling partners to retrieve performance metrics for their offers.
How should Demand Partners provide merchant and offer data to CDLX?
Demand Partners can provide merchant and offer data through two methods: daily SFTP file uploads or via REST APIs for near real-time updates. For SFTP, partners upload JSON formatted files containing a full dump of all active merchants or offers, categorized as NEW, UPDATED, NO-CHANGE, or DELETED. For REST APIs (recommended for partners with fewer than 100 merchants for merchant updates), partners can send individual JSON payloads for creating, updating, or deleting merchants and offers in near real-time.
What are the key requirements for the merchant and offer data files uploaded via SFTP?
Files must be JSON formatted and named according to the convention <Partner_Name>MerchantsCCYYMMDD.json for merchants and <Partner_Name>OffersCCYYMMDD.json for offers. Each file must be a full dump containing all active records with a header record specifying the file description, creation date, and record count. Each merchant and offer record must include a merchantStatus or offerStatus field indicating whether the record is NEW, UPDATED, DELETED, or NO-CHANGE.
How does CDLX handle updates and deletions of merchants and offers?
For SFTP uploads, partners indicate changes through the merchantStatus and offerStatus fields (NEW, UPDATED, DELETED). CDLX processes the entire file daily, updating or deleting records based on these statuses. For REST APIs, partners explicitly call PUT endpoints to create or update and DELETE endpoints to remove individual merchant or offer records. It's important to note that even if an offer is deleted by the partner, it will remain valid for customers who have already activated it until the end of its 30-45 day redemption period.
How frequently are merchant and offer data expected to be updated?
For SFTP, if there are any new, updated, or deleted merchants or offers, a new file must be uploaded daily. If there are no changes, no upload is required, and CDLX will continue using the previously uploaded data. For REST APIs, updates should be sent in near real-time only when a merchant or offer is created, modified, or needs to be deleted.
What information is included in the Redemption Feed, and how can partners access it?
The Redemption Feed contains daily files uploaded by CDLX, providing details of transaction redemptions. This includes a unique, anonymized transaction ID, partner-provided merchant and offer IDs, store ID, merchant name, card type, last four digits of the card, transaction amount, and a transaction timestamp in ISO 8601 format. Partners can access and pull this file daily via SFTP.
What kind of performance reporting does CDLX provide to Demand Partners?
CDLX provides an Aggregate Reporting API that allows partners to retrieve offer performance metrics at both the merchant and offer levels. Partners can invoke this API to access detailed reporting data such as purchases, revenue, reach, impressions, and activations. The API supports filtering by specific offer IDs (up to 1000 at a time) and a specified time range.
What are the key considerations and guidelines for ensuring a successful integration?
Successful integration relies on proper formatting and adherence to the specified JSON schemas for all data exchanges. Partners should ensure consistency in merchant and offer identifiers across all updates. When using SFTP, full dumps must be provided with each update. For REST APIs, partners should stay within the provided daily quota and requests per second (RPS) limits to avoid HTTP 429 errors. It is also crucial for partners to understand the file naming conventions and the meaning of the status fields for both merchant and offer data.