Performance Reporting

📚

Quick Links:

• 🚀 Try the API → Jump straight into testing the Merchant Performance Reporting endpoint.

• 📖 View Complete API Reference → Explore all endpoints, schemas, and examples.

Abstract

The Reporting API facilitates the structured request for partner demand performance metrics, supporting HTTP REST protocols. The API defines a clear schema requesting for metrics with a specified list of filtering criteria.

This document outlines the use of a REST API to pull reporting metric data.

Partners interact with the API by sending POST requests to make a reporting query for performance metric results that can be filtered by a date range and by the partner's self-provided merchant ID and optional offer IDs; same IDs used from when submitting merchants and offers as part of the ingestion integration process. The system enforces daily call quotas and requests-per-second (RPS) limits, returning HTTP 429 on quota violations.

The document includes endpoint details and emphasizes that proper usage ensures timely reports.

Purpose

• Reporting API that partners can invoke to get the performance metrics for their running merchants and offers
• Partners can invoke this API to access detailed reporting for a specified date range.

How It Works

• We provide a REST API to make it easier to provide near real-time reporting metrics.

📘

Please keep the following in mind:

• One merchant ID supported per request at a time.
• Date range filter cannot exceed more than 2 years back.
• Most offer engagement event data (e.g. impressions, activations) have an hour delay for data completeness.
• Most spend-related data (e.g. purchases) can have up to 7 days delay for data completeness due to a lag time in data delivery from some publishers.

Recommendations on how to call

• Partner begins with calling Reporting endpoint “POST /api/v1/partner/merchants/{external_merchant_id}/reports one merchant at a time within the limits of the RPS.
• From the merchant offers provided, Cardlytics will handle aggregating data across all running continuous engagement based campaign flights with various redemption windows ranging from 30-45 days.

❗️

Important: Because offers running on our network across our supply are activatable card-linked offers, we are obligated to our consumers who activated to retain the offers until redemption expiry. When a Partner sends a signal to "take down" or delete a merchant offer, note that for any customer that activates the offer, it will continue to be valid and paid out for redemption until the remaining 30-45 day redemption period winds down. For these reasons, you may still see serves, activations, and other events for those dates post merchant offer deletion.

Guard Rails

• Every Partner will be provided with a daily quota of the number of calls they can make, this should be ~ Number of merchant offers
• Every Partner will be provided with an RPS, for example, 10 calls per second
• API will return HTTP 429 if a Partner exceeds the quota of the daily limit or RPS

Endpoint Details

Get merchant performance report for specified partner self-provided merchant ID and date range

Request Schema

Request Payload Sample

{
  "cube": "merchant_performance",
  "offerIds": [],
  "timeRange": {
    "from": "2023-10-01",
    "to": "2025-09-17"
  }
}

Response Schema

Response Payload Sample

{
    "header": {
        "cube": "merchant_performance",
        "fields": [
            {
                "fieldName": "Partner Merchant Id",
                "fieldType": "DIM"
            },
						{
                "fieldName": "Partner Offer Id",
                "fieldType": "DIM"
            },
            {
                "fieldName": "Impressions",
                "fieldType": "FACT"
            },
            {
                "fieldName": "Purchases",
                "fieldType": "FACT"
            },
            {
                "fieldName": "Revenue",
                "fieldType": "FACT"
            },
            {
                "fieldName": "Reach",
                "fieldType": "FACT"
            },
            {
                "fieldName": "Activations",
                "fieldType": "FACT"
            }
        ]
    },
    "rows": [
        [
          	"88d4d968-e922-sample-partner-merchant-id-f32a0eaa43ff",
						"2e1fd66d-72d7-sample-partner-offer-id-af82-b4bfd0aaa7ac",
            280568,
            14,
            714.87,
            172472,
            8005
        ],
        [
          	"88d4d968-e922-sample-partner-merchant-id-f32a0eaa43ff",
						"5555d66d-72d7-sample-partner-offer-id-af82-343430aaa7ac",
            100568,
            08,
            14.22,
            2472,
            807
        ]
    ]
}

Field Name Definitions

📘

Interactive API Testing

Ready to test the API? 👉 Visit our Interactive API Reference to try out endpoints with real requests.