Redemption Feed

Abstract

This document provides a comprehensive guide to the Redemption Feed, a crucial data stream designed to empower our advertiser partners with anonymized transaction insights. By understanding the structure, delivery, and nuances of this feed, you can effectively measure offer performance and gain valuable insights into consumer behavior.

Overview

The document details the structure and delivery of the Redemption Feed, a data file securely provided by Cardlytics to our partners. This feed contains anonymized transaction records, offering essential details such as transaction ID, cardholder ID, merchant and offer identifiers, store information, merchant name, card type, and the last four digits of the card (if available), along with the transaction amount and timestamp. All fields are required unless explicitly noted. Cardlytics ensures timely delivery by uploading these Redemption Feed files hourly, which partners can then securely retrieve via SFTP.

Data Anonymization and Privacy

At Cardlytics, consumer privacy is paramount. We are committed to providing robust data insights while strictly adhering to privacy-by-design principles. Here's how we ensure data anonymization:

• Transaction and Cardholder Anonymized Identifiers: All transaction records within the Redemption Feed utilize highly anonymized and obfuscated identifiers for both transactions and cardholders. These identifiers are unique to each transaction and cardholder within the Cardlytics ecosystem and are not traceable back to any personally identifiable information (PII) of the consumer. For each partner, these identifiers are further obfuscated to ensure no cross-partner PII linkage.
• No Sharing of Personally Identifiable Information (PII): Cardlytics never shares raw PII such as names, addresses, full card numbers, or any other direct identifiers with our advertiser partners. Our platform is designed to operate behind financial institution firewalls, processing data in a secure, anonymized environment.

Redemption Feed Details

The Redemption Feed provides a detailed view of successful offer redemptions. Each row in the feed represents a unique, anonymized transaction where a Cardlytics offer has been redeemed.

Edge Cases for card_type and card_last_four:

As indicated, card_type and card_last_four are nullable fields. This means:

• Null or Empty Values: These fields may be null or empty in the Redemption Feed if the underlying card network data or the last four digits are not consistently available from the financial institution's transaction records. While Cardlytics strives to provide as much detail as possible, data availability can vary.
• Handling in Partner Systems: Partners should design their systems to gracefully handle instances where card_type or card_last_four are null or empty. It is not an error state from Cardlytics' perspective. Your processing logic should anticipate and manage these missing values without causing data pipeline failures or misinterpretations. For reporting or analytics, consider these as "unknown" or "unavailable" rather than erroneous data points.

Cadence and Lookback

• Cadence: Any delta (new or updated redemption records) will be sent as and when available, typically down to the hour. This means that Cardlytics uploads Redemption Feed files hourly to your SFTP destination, providing near real-time updates on offer redemptions. Partners should retrieve these files hourly to maintain the freshest view of their campaign performance.
• Lookback for Redemptions is 90 Days: This refers to the period during which Cardlytics considers a transaction eligible for an offer redemption. If an offer is activated, and a qualifying transaction occurs within 90 days of that activation, it will be considered a redemption and included in the Redemption Feed. Transactions occurring outside of this 90-day lookback window (e.g., a transaction from 91 days ago) will not be attributed as a redemption for active offers, even if they would otherwise qualify. This ensures that redemption data reflects recent and relevant consumer behavior in relation to current offers.

Validation Per Field

While the "Note" column in the table above provides some context, this section clarifies the specific validation rules for each field to ensure partners can correctly process the Redemption Feed.

• transaction_id:

  • Format: String.
  • Uniqueness: Guaranteed to be unique across all transactions within the Cardlytics platform for a given partner.
  • Content: An opaque, obfuscated identifier. Should not be parsed for meaning.
  • Required: Yes. Will always be present.

• cardholder_id:

  • Format: String.
  • Uniqueness: Guaranteed to be unique for each anonymized cardholder for a given partner.
  • Content: An opaque, obfuscated identifier. Should not be parsed for meaning.
  • Required: Yes. Will always be present.

• partner_merchant_id:

  • Format: String.
  • Content: Expected to match the merchant ID provided by the partner during their merchant data ingestion.
  • Validation: Partners should validate this against their own internal merchant master data. If a partner_merchant_id in the feed does not match a known ID, it indicates a discrepancy in partner-provided data.
  • Required: Yes. Will always be present.

• partner_offer_id:

  • Format: String.
  • Content: Expected to match the offer ID provided by the partner during their offer data ingestion.
  • Validation: Partners should validate this against their own internal offer master data. Discrepancies may indicate issues with offer setup or data synchronization.
  • Required: Yes. Will always be present.

• partner_store_id:

  • Format: String.
  • Content: Expected to match the store ID provided by the partner. Can be null or empty if a store ID was not provided or is not applicable to the transaction (e.g., pure online transactions without a specific store mapping).
  • Validation: Partners should validate this against their own internal store master data if applicable.
  • Required: Yes. Will always be present.

• partner_merchant_name:

  • Format: String.
  • Content: The human-readable name of the merchant.
  • Validation: Primarily for display and reconciliation. Partners may use this for lookup or logging.
  • Required: Yes. Will always be present.

• card_type:

  • Format: String.
  • Expected Values: Typically "Visa", "Mastercard", "American Express", "Discover", etc. (case-insensitive for robust parsing).
  • Validation: Partners should be prepared for various card network names and for null or empty values.
  • Required: No (Nullable).

• card_last_four:

  • Format: String.
  • Content: Exactly four numeric characters representing the last four digits of the card number.
  • Validation: Should be a string of length 4 containing only digits. Partners should be prepared for null or empty values.
  • Required: No (Nullable).

• transaction_amount:

  • Format: Number (decimal, typically representing currency).
  • Content: The monetary value of the transaction. Cardlytics will provide this in the currency relevant to the transaction's origin (e.g., USD for US transactions).
  • Validation: Should be a valid numeric value.
  • Required: Yes. Will always be present.

• transaction_timestamp:

  • Format: String, ISO 8601 format (e.g., YYYY-MM-DDTHH:MM:SSZ). The 'Z' indicates UTC time.
  • Content: Represents the exact time the transaction occurred.
  • Validation: Must conform to the ISO 8601 standard for date and time.
  • Required: Yes. Will always be present.

Error Codes

The Redemption Feed itself is a data file delivered via SFTP, so it does not have real-time API error codes in the traditional sense for individual record failures. However, potential issues in the file delivery or data quality can manifest in different ways.

SFTP Delivery Errors:

• Connection/Authentication Errors: Issues with your SFTP client connecting to the Cardlytics SFTP server, or incorrect credentials. These would be client-side errors reported by your SFTP software.
  • Resolution: Verify SFTP hostname, port, username, password/key. Check network connectivity.
• File Not Found/Permissions: If expected files are not present or you lack permissions to download them.
  • Resolution: Confirm file naming conventions and paths. Contact Cardlytics support to verify your SFTP user permissions.
• Incomplete File Transfer: The file download might be interrupted, resulting in a partially transferred or corrupted file.
  • Resolution: Implement robust SFTP client logic for retries and checksum verification if supported. Cardlytics aims for atomic file delivery.

Data Quality / Content Errors within the Feed (Post-Download):

While Cardlytics aims to provide clean data, partners should implement robust parsing and validation within their own systems to handle unexpected data. These are not "error codes" from Cardlytics but rather potential issues your system might encounter:

• Malformed Data: A row might not conform to the expected CSV/JSON structure (though CSV is typical for SFTP feeds).
  • Impact: Row parsing failure.
  • Resolution: Log the problematic row, skip it, and investigate the file for corruption.
• Missing Required Fields: A field marked "No" under "Nullable" in the table above is empty or missing.
  • Impact: Data integrity issue, potential processing failure.
  • Resolution: This should ideally not happen. If it does, log the record as an error and alert Cardlytics support with the specific transaction_id and field.
• Invalid Data Format: A field's content does not match its expected format (e.g., transaction_amount is not a number, transaction_timestamp is not ISO 8601).
  • Impact: Data type conversion errors, incorrect calculations.
  • Resolution: Implement strict data type validation. Records with invalid formats should be flagged for review and potentially quarantined.
• Unexpected Values: For card_type, receiving a value not in the common list (e.g., "Unknown Card").
  • Impact: May require flexible parsing or additional mapping logic.
  • Resolution: Treat as an acceptable but uncommon value or map to a generic "other" category.

Contacting Cardlytics Support:

For any persistent SFTP delivery issues or if you encounter widespread data quality problems within the Redemption Feed, contact your dedicated Cardlytics Partner Success Manager or the Cardlytics Support team with detailed information (file names, timestamps of issues, specific error messages from your systems).