Revenue Report

The revenue report is for supply account owners (e.g. retailers) to understand where their retail media revenue is coming from, providing full visibility across all advertisers, media, and direct/indirect sales channels.

The revenue report gives insight on generated revenue, delivered impressions and clicks, average rates, and performances.

Endpoints

The revenue report uses an asynchronous endpoint that is used to create the report, and then using the report id to download or view the report status using the following GET endpoint requests.

Verb	Endpoint	Description
POST	`/retail-media/reports/revenue`	Generate a retailer revenue report
GET	`/reports/{reportId}/output`	Download Output of a Specific Report
GET	`/reports/{reportId}/status`	Get Status of a Specific Report

Attributes

Data Type: string

Description: The supply account ID or IDs to pull results for

Note: For apps with access to multiple supply accounts, you also have the option to use an ids array to multiple ids. This can be used when you wish to pull results across multiple accounts. e.g. "ids":["supplyAccountId_1","supplyAccountId_2"]

Accepted Values: One or multiple supply account id(s) in a string format

ids

Data Type: string array

Description: Campaign ids to report on

Accepted Values: An array of campaign ids to report on

reportType

Data Type: string

Description: the report type allows to specify the report breakdown. It allows to generate the report to view revenue distribution by advertiser, brand, environment, pageCategory, pageType

Accepted Values: advertiser, brand, environment, productCategory, pageType

revenueType

Data Type: enum

Description: The campaign 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

soldBy

Data Type: string

Description: The campaign buy types

Accepted Values: directSold, indirectSold, privateMarket

salesChannel

Data Type: enum

Description:Filter the sales channel the attributed purchase was made through

Accepted Values: offline, online

campaignSubType

Data Type: enum

Description: The campaign subtype booked by the advertiser

Accepted Values: auctionAndPreferred, lockout

format

Data Type: enum

Description: The report format type to return results

Accepted Values: json, json-compact, json-newline, csv

startDate

Data Type: date-time

Description: Earliest day to report; inclusive

Accepted Values: YYYY-MM-DD

endDate

Data Type: date-time

Description: Latest day to report; inclusive

Accepted Values: YYYY-MM-DD

metrics

Data Type:string

Description:Metrics attributes to filter report results

Accepted Values: impressions, clicks, spend, sales, units, cpo, roas, openAuctionRevenue, preferredDealsRevenue, avgCpc, avgCpm

dimensions

Data Type:string

Description:Dimension attributes to filter report results

Accepted Values: date, campaignId, campaignName, accountId, environment, advProductCategory, brandId, brandName, pageTypeName, advProductName, advProductGtin, advProductMpn, advProductId

timezone

Data Type: string

Description: Time zone of the report

Accepted Values: database tz syntax , eg. America/New_York, Europe/Paris, Asia/Tokyo, UTC

viewAttributionWindow

Data Type: string

Description: View attribution window

Accepted Values: 1D, 7D, 14D, 30D, none

clickAttributionWindow

Data Type: string

Description: Click attribution window

Accepted Values: 7D, 14D, 30D, none

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: text/plain' \
-H 'Authorization: Bearer <TOKEN>' \
-d '{
	"data": {
		"type": "<string>",
		"attributes": {
			"endDate": "2024-02-14",
			"startDate": "2024-02-01",
			"reportType": "environment",
			"revenueType": "auction",
			"id": "203209148566716416",
			"metrics": [
				"avgCpm",
				"openAuctionRevenue"
			],
			"dimensions": [
				"brandId",
				"pageTypeName"
			],
			"format": "json",
			"soldBy": "indirectSold",
			"campaignSubType": "auctionAndPreferred",
			"clickAttributionWindow": "7D",
			"viewAttributionWindow": "1D",
			"campaignType": "sponsoredProducts",
			"salesChannel": "online",
			"timezone": "UTC"
		}
	}
}'

Sample Response

{
    "data": {
        "attributes": {
            "status": "pending",
            "rowCount": 0,
            "fileSizeBytes": 0,
            "md5CheckSum": null,
            "createdAt": "2024-02-14T18:20:25.130Z",
            "expiresAt": null,
            "message": null,
            "id": "xxxxxx-xxxx-xxxx-xxxx-97debd9190bc"
        },
        "id": "xxxxxx-xxxx-xxxx-xxxx-97debd9190bc",
        "type": "StatusResponse"
    },
    "warnings": [
        {
            "traceId": null,
            "traceIdentifier": null,
            "type": "validation",
            "code": "ignored-report-type",
            "instance": null,
            "title": "Report Type has been ignored",
            "detail": "Report Type has been ignored since Dimensions and Metrics has been provided. Please remove them if you want to use one of the templates.",
            "source": null
        }
    ],
    "errors": []
}

Get Status of a 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-17a42f4267cb/output" \
    -H "Authorization: Bearer <MY_ACCESS_TOKEN>"

Sample Responses

Report broken down by advertiser by JSON

[
    {
        "brandId": -1,
        "pageTypeName": "category",
        "openAuctionRevenue": 0E-8,
        "avgCpm": null
    },
    {
        "brandId": 1234,
        "pageTypeName": "category",
        "openAuctionRevenue": 63.94733334,
        "avgCpm": null
    },
    {
        "brandId": 5678,
        "pageTypeName": "category",
        "openAuctionRevenue": 762.95292406,
        "avgCpm": null
    }
]

Metrics and Dimensions

Metric	Report Types	Revenue Type	Description
`date`	All report types	auction, preferred	The date of when revenue was generated
`accountId`	Advertiser only	auction, preferred	The advertiser id
`accountName`	Advertiser only	auction, preferred	The advertiser where revenue originated from
`environment`	Environment only	auction, preferred	The environment type where revenue was generated
`brandId`	Brand only	auction only	The brand id
`brandName`	Brand only	auction only	The brand name
`pageTypeName`	Page Type only	auction, preferred	The page type from where revenue was generated
`impressions`	All report types	auction, preferred	Measures the number of impressions generated by the advertiser, brand, page type, page category or environment
`clicks`	All report types	auction, preferred	Number of clicks the advertiser, brand, page type, page category or environment helped generate revenue for the retailer
`openAuctionRevenue`	All report types	auction, preferred	The total amount of open auction revenue generated on the set date
`preferredDealsRevenue`	All report types	auction, preferred	The total amount of preferred deals revenue generated on the set date
`avgCpc`	All report types	auction	Average cost-per-click calculated by dividing `openAuctionRevenue` / `clicks` or `preferredDealsRevenue` / `clicks`
`avgCPM`	All report types	preferred	Average cost per mille calculated by diving `preferredDealsRevenue` / `impressions` * 1000
`roas`	All report types	auction, preferred	Return-on-ad-spend (ROAS), calculated by dividing `sales` / `openAuctionRevenue` or `sales` / `preferredDealsRevenue`
`units`	All report types	auction, preferred	Number of units attributed to the generated revenue
`sales`	All report types	auction, preferred	Number of sales attributed to the generated revenue

Responses

Response	Description
🔵 `200`	Call executed with success
🔴 `400`	Common Validation Errors endDate cannot be more than 100 days from startDate - Using a date range with more than 100 days apart reportType invalid - calling an unsupported report type will throw a 400 error timeZone must 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

Response

Description

🔵 200

Call executed with success

🔴 400

Common Validation Errors

endDate cannot be more than 100 days from startDate - Using a date range with more than 100 days apart
reportType invalid - calling an unsupported report type will throw a 400 error
timeZone must 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