Overview: Merchant Data and Offer Data

This document provides a comprehensive introduction to integrating with our platform using Merchant Data and Offer Data. It covers the purpose and structure of the required data, best practices for data submission, validation, and error handling, as well as key considerations to ensure a seamless and effective integration for partners, merchants, and end users.

1. Merchant Data

Structure and Rationale

Merchant Data is composed of two primary entities: merchants and stores.

• Merchants represent the overarching business entity (e.g., a chain or brand).
• Stores are the individual physical or digital locations where transactions occur.

Why Both?
Capturing both merchants and stores enables precise transaction matching and redemption processing. A merchant may operate multiple stores, each with distinct details such as address, contact information, or operational hours. Providing a list of stores ensures that offers and redemptions are accurately attributed, improving reporting and user experience.

Data Completeness

Recommendation:
Partners are encouraged to provide as much detail as possible, such as phone numbers and merchant URLs. Comprehensive data leads to greater accuracy in transaction matching and redemption, benefiting both merchants and end users.

Data Submission Best Practices

• Frequency: Send merchant and store updates as frequently as changes occur to maintain accuracy.
• Timeliness: Promptly reflect any changes (e.g., new stores, closures, contact updates) to minimize discrepancies.
• Accuracy: Ensure all fields are current and validated to avoid processing issues.

2. Offer Data

Offer Lifecycle Management

When submitting Offer Data, it is critical to manage the offer lifecycle, especially when deleting offers.

Importance of the DELETE Signal

Timely DELETE signals for offers are necessary to prevent unintended campaigns and activations.

• Our platform serves major financial institutions and prioritizes a positive, consistent end-user experience.
• Offers cannot always be instantly removed; they may remain active for up to 30 days if a campaign is in progress.
• DELETE signals ensure offers are phased out appropriately and reduce the risk of user confusion or negative experiences.

Image Specifications

• Large Rectangle Image:

  • Purpose: Used as prominent visual assets in many cases as background or "hero" image in majority of our supply. While not always rendered, it is required for wider onboarding options across our supply partners.
  • Sample:
  
  
  • Type: We recommend JPG when possible, PNG also supported.
  • Dimensions: 1200px by 627px exact size is required.
  • File Size: We recommend no more than 2MB, max 5MB is the limit.
  • Transparency: Highly discouraged. Most of our supply does not support transparent images.
  • Imagery Content: Can be branded, specific restaurant, or generic cuisine type or food images — flexible based on the merchant.

• Logo Image:

  • Purpose: Used as the smaller brand logo image in all of our supply. This is always rendered as it indicates the merchant brand name or visual.
  • Sample:
  
  
  • Type: We recommend JPG when possible, PNG also supported.
  • Dimensions: 627px by 627px exact size is required.
  • File Size: We recommend no more than 2MB, max 5MB is the limit.
  • Transparency: Not accepted. Most of our supply does not support transparent images and with logos or it may collide with representation.
  • Imagery Content: Logo image should represent the brand or merchant's company logo or name.
  • Safe Area Guidelines:
    We require a designated, smaller circular area of 523x523 px within your provided image to contain all the essential elements. Think of it as a guaranteed "no-crop zone." Its primary purpose is to ensure that the most critical parts of your logo—like your company name, main graphic—are always visible and never awkwardly cut off, no matter how the image is automatically resized or framed. Some of our supply render the logo image as rounded and following this safe area best practice, will ensure nothing crucial is cropped off. Please see sample cropping below.

Overview: Redemption and Performance Data

1. Redemption Feed

Structure and Rationale

When parsing Redemption Data, it is important to understand that while most fields will have always have non-empty values, there are rare occasions where we are unable to provide values due to various events for the following fields:

• card_type
• card_last_four

The following fields are unique identifiers that are anonymized as part of the feed:

• transaction_id
• cardholder_id

Fields with the prefix partner_ indicate fields we tag and mark the redemptions with identifiers you provide us via merchant and offer APIs (e.g. partner_merchant_id).

Frequency and Cadence

We will be including all redemptions that our platform receives for transactions that are determined to fulfill the redemption qualification requirements. Redemptions will be made available as they come from our supply as granular as hourly feeds and delayed up to several days after the transaction took place.

2. Aggregate Reporting API (Insights and Performance Metrics)

More best practices and details coming soon.

Summary

Successful integration depends on:

• Providing complete, up-to-date, and accurate Merchant and Offer Data.
• Adhering to best practices for data submission frequency and validation.
• Understanding the importance of timely DELETE signals for offers.
• Following industry standards and safe area best practices for image assets.
• Referring to comprehensive validation and error code documentation beyond what is provided in the Swagger API reference.