Revenue Report

Supply Side Revenue Report (v2)

Introduction

The revenue report serves as a vital tool for supply account owners, such as retailers, enabling them to understand the origins of their retail media revenue. It offers comprehensive visibility across all advertisers, media platforms, and sales channels, encompassing direct, indirect, and private market avenues.

This report delves into crucial aspects, including generated revenue, delivered impressions, clicks, average rates, and overall performance metrics. Through this API only, supply partners gain the ability to construct detailed reports by accessing several metrics and dimensions.

🟠

Default settings

When a retailer wants to view their default settings (as used in the user interface), we suggest constructing their API request or data call using the same default parameters that the UI uses. The specific default values used by the system are documented in Criteo Help Center.


Endpoints

The report generation uses an asynchronous endpoint that is used to receive the report creation request (using a POST request). Then, using the report id generated, it's possible to check the report status and to download the output results using the following GET endpoint requests.

VerbEndpointDescription
POST/reports/revenueRequest a retailer revenue report creation
GET/reports/{reportId}/statusGet status of a specific report
GET/reports/{reportId}/outputDownload output of a specific report

Attributes

Attribute

Data Type

Description

id

string

Supply Account ID to pull results for

Note: for apps with access to multiple supply accounts, it is also possible to use an ids array for multiple IDs, allowing to pull results across multiple accounts. e.g.
"ids":["supplyAccountId_1","supplyAccountId_2"]

Accepted values: int64
Writable? N / Nullable? N

reportType

enum

Report types are pre-packaged reports that allow the specification of the report breakdown. They enable reports to view revenue distribution by advertiser, brand, environment, page category, and page type. The metrics and dimensions in these report types are limited.
Use the metrics and dimensions arrays to build your report for additional fields.

Note: when metrics and dimensions are used, the report type is ignored.

Accepted values: advertiser, brand, environment, productCategory, pageType
Writable? N / Nullable? Y

revenueType

enum

The revenue type used to filter report results.
If the revenue type filter is not specified, the report will return all existing revenue data for sponsored products and preferred deals within the specified timeframe.

Accepted values: auction, preferred
Writable? N / Nullable? Y

soldBy

enum

The sales channel of indirect sold, direct sold, or private market. This is an optional filter that can be used to narrow down results.

Accepted values: directSold, indirectSold, privateMarket
Writable? N / Nullable? Y

buyType

enum

The campaign buying strategy. This optional filter can be used to filter down results

Accepted values: auction, preferredDeals, sponsorship
Writable? N / Nullable? Y

format

enum

The format type the report should return results

Accepted values: json, json-compact, json-newline, csv
Writable? N / Nullable? N

campaignType

enum

The campaign type to filter results

Accepted values: all, sponsoredProducts, onSiteDisplays
Default: all
Writable? N / Nullable? N

salesChannel

enum

The sales channel where attributed sales originated

Accepted values: all, online, offline
Default: all
Writable? N / Nullable? N

advertiserTypes

list<string>

The advertiser type where campaigns originated from

Accepted values: retailer, brand, seller
Writable? N / Nullable? N

clickAttributionWindow

enum

The post-click attribution window, defined as the maximum number of days considered between a click and a conversion for attribution; conversions are attributed to the date of conversion, not the date of click.

Accepted values: none, 7D, 14D, 30D
Default: if omitted, defaults to Campaign settings; must be specified if viewAttributionWindow is one of the accepted values
Writable? N / Nullable? Y

viewAttributionWindow

enum

The post-view attribution window, defined as the maximum number of days considered between an impression and a conversion for attribution; conversions are attributed to the date of conversion, not the date of impression.

Accepted values: none, 1D, 7D, 14D, 30D
Default: if omitted, defaults to Campaign settings; must be less than or equal to clickAttributionWindow; must be specified if clickAttributionWindow is one of the accepted values
Writable? N / Nullable? Y

dimensions

list<enum>

An array of strings used to define which dimensions to see in the report

Accepted values: refer to Metrics and Dimensions for the complete list of supported dimensions
Writable? N / Nullable? Y

clickMatchLevel

string

The attribution configuration modal allows users to retrieve data based on the specified product match for click events.

The order of product match relationships from farthest to closest is sameBrand < sameCategory < sameSku. ThesameBrand product match value is inclusive of sameCategory and sameSkuattribution. The sameCategory value is inclusive of sameSku attribution. Only one value should be used.

This is not a filter that excludes events. Rather, it calculates attribution using the provided SKU match level.

Accepted values: sameSku, sameCategory, sameBrand, campaign
Default: if omitted, defaults to Campaign settings
Writable? N / Nullable? Y

viewMatchLevel

string

The attribution configuration modal allows users to retrieve data based on the specified product match for view events.

The order of product match relationships from farthest to closest is sameBrand < sameCategory < sameSku. ThesameBrand product match value is inclusive of sameCategory and sameSkuattribution. The sameCategory value is inclusive of sameSku attribution. Only one value should be used.

This is not a filter that excludes events. Rather, it calculates attribution using the provided SKU match level.

Accepted values: sameSku, sameCategory, sameBrand, campaign
Default: if omitted, defaults to Campaign settings
Writable? N / Nullable? Y

skuRelations

(DEPRECATED)

string

The attributed rule used to match an impression/click to a sale. The filter will narrow down results of the attributed rules set by the advertiser at the campaign level.

Accepted Values: sameSku, sameParentSku, sameCategory, sameBrand, sameSeller
Writable? N / Nullable? Y

⚠️Note: This filter is deprecated. Please use clickMatchLevel and viewMatchLevel instead. However, the skuRelations dimension can still be used.

metrics

list<enum>

An array of strings used to define which metrics to see in the report.

Accepted values: refer to Metrics and Dimensions for the complete list of supported metrics
Writable? N / Nullable? Y

startDate

timestamp

Start date of the report (inclusive)

Accepted values: yyyy-mm-ddThh:mm:ss(in ISO-8601 )
Writable? N / Nullable? N

endDate

timestamp

End date of the report (inclusive)

Accepted values: yyyy-mm-ddThh:mm:ss(in ISO-8601 )
Writable? N / Nullable? N

timezone

string

Time zone to consider in the metrics calculation,startDate and endDate

Accepted values: IANA (TZ database) time zones (example: America/New_York, Europe/Paris, Asia/Tokyo, UTC)
Default: UTC
Writable? N / Nullable? Y

accountIds

string

Gives the ability for the user to filter by account IDs.

There are currently no limitations to the amount of IDs that can be added to the filter.

campaignIds

string

Gives the ability for the user to filter by campaign IDs.

There are currently no limitations to the amount of IDs that can be added to the filter.

lineItemIds

string

Gives the ability for the user to filter by line item IDs.

There are currently no limitations to the amount of IDs that can be added to the filter.

retailerIds

string

Gives the ability for the user to filter their reporting by retailer ID(s).

📘

Metrics and Dimensions

For a complete list of all supported metrics and dimension, check out the Metrics and Dimensions

👍

When utilizing the clickMatchLevel and viewMatchLevel fields, we recommend including the attributionSettings, activityType, and skuRelation. This will assist in gaining a clearer understanding of the click and view events, categorized by their attribution windows and SKU relationships.


Generate Revenue Report

https://api.criteo.com/{version}/retail-media/reports/revenue

Sample Request

curl -L 'https://api.criteo.com/{version}/retail-media/reports/revenue' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <MY_ACCESS_TOKEN>' \
-d '{
  "data": {
        "type": "SSPRevenueReport",
        "attributes": {
          "id": "203209148566716416",
          "revenueType": "auction",
          "soldBy": "directSold",
          "buyType": "auction",
          "skuRelations": [
            "sameSku"
          ],
          "format": "json",
          "campaignType": "sponsoredProducts",
          "salesChannel": "online",
          "clickAttributionWindow": "7D",
          "viewAttributionWindow": "1D",
          "clickMatchLevel": "sameCategory",
          "viewMatchLevel": "sameSKU",
					"dimensions": [
              "date",
              "hour",
              "advertiserType",
              "accountName",
              "campaignName",
              "activityType",
              "advProductId",
              "advProductName",
              "placementName",
              "taxonomy1Name",
              "taxonomy2Name",
              "taxonomy3Name"      
          ],
          "metrics": [
              "numberOfCampaigns",
              "numberOfSkus",
              "clicks",
              "units",
              "ctr",
              "cr",
              "workingMedia",
              "netRevenue"
          ],
          "startDate": "2024-04-10T21:14:53.816Z",
          "endDate": "2024-04-10T21:14:53.816Z",
          "timezone": "UTC"
     	 }
    }
  }
}'

Sample Response

{
    "data": {
        "type": "RetailMediaReportStatus",
        "id": "22fa642d-ab8a-463c-a2f6-fb174c2f72dd",
        "attributes": {
            "status": "pending",
            "rowCount": null,
            "fileSizeBytes": null,
            "md5Checksum": null,
            "createdAt": null,
            "expiresAt": null,
            "message": null
        }
    }
}

Get status of specific report

https://api.criteo.com/{version}/retail-media/reports/{reportId}/status

Sample Request

curl -L 'https://api.criteo.com/{version}/retail-media/reports/22fa642d-ab8a-463c-a2f6-fb174c2f72dd/status' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <MY_ACCESS_TOKEN>'

Sample Response

{
    "data": {
        "type": "RetailMediaReportStatus",
        "id": "22fa642d-ab8a-463c-a2f6-fb174c2f72dd",
        "attributes": {
            "status": "success",
            "rowCount": 2,
            "fileSizeBytes": 341,
            "md5Checksum": "f43cf2503a31a100f7b81db3c14d3fae",
            "createdAt": "2023-07-10T16:00:32.000Z",
            "expiresAt": "2023-07-17T16:00:32.000Z",
            "message": null
        }
    }
}

Download Output of a Specific Report

https://api.criteo.com/{version}/retail-media/reports/{reportId}/output

Sample Request

curl -X GET "https://api.criteo.com/{version}/retail-media/reports/2e733b8c-9983-4237-aab9-17a42f426xx/output" \
    -H "Authorization: Bearer <MY_ACCESS_TOKEN>"

Sample Responses

Report broken down by advertiser by JSON format

[
    {
        "date": "2024-04-10",
        "hour": 15,
        "advertiserType":"seller",
        "accountName": "Account A",
        "campaignName": "CampaignABC",
        "placementName": "viewSearchResult",
        "activityType": "imp",
        "advProductId": "14364409",
        "advProductName": "360 Deluxe (PC/Mac) - 5 Devices",
        "taxonomy1Name": "computers & tablets",
        "taxonomy2Name": "software",
        "taxonomy3Name": "antivirus, security & utility software",
        "numberOfCampaigns": 1,
        "numberOfSkus": 1,
        "clicks": 0,
        "units": 1,
        "ctr": null,
        "cr": null,
        "workingMedia": 0,
        "netRevenue": 0
    },
    {
        "date": "2024-04-10",
        "hour": 11,
        "advertiserType":"brand",
        "accountName": "Account A",
        "campaignName": "CampaignXYZ",
        "placementName": "viewSearchResult",
        "activityType": "click",
        "advProductId": "15325425",
        "advProductName": "Mini On-Ear Bluetooth Kids Headphones - Pink",
        "taxonomy1Name": "audio",
        "taxonomy2Name": "headphones",
        "taxonomy3Name": "over-ear headphones",
        "numberOfCampaigns": 1,
        "numberOfSkus": 1,
        "clicks": 0,
        "units": 1,
        "ctr": null,
        "cr": null,
        "workingMedia": 0,
        "netRevenue": 0
    },
    {
        "date": "2024-04-10",
        "hour": 10,
        "advertiserType":"seller",
        "accountName": "Account B",
        "campaignName": "CampaignDEF",
        "placementName": "viewItem_API",
        "activityType": "imp",
        "advProductId": "17701444",
        "advProductName": "City Pro Electric Scooter",
        "taxonomy1Name": "sports, recreation & transportation",
        "taxonomy2Name": "electric transportation",
        "taxonomy3Name": "electric scooters",
        "numberOfCampaigns": 1,
        "numberOfSkus": 1,
        "clicks": 0,
        "units": 1,
        "ctr": null,
        "cr": null,
        "workingMedia": 0,
        "netRevenue": 0
    }
]

Responses

Response

Description

🔵 200

Call executed with success

🔴 400

Common Validation Errors:

  • endDate cannot be more than 100 days fromstartDate - Using a date range with more than 100 days apart
  • reportTypeinvalid - calling an unsupported report type will throw a 400 error
  • timeZonemust be a valid timezone - using a time zone value that is not listed in the list tz database time zones
  • format invalid - using an unsupported file format