--- updatedAt: 2025-09-30T17:52:46.000Z agentTools: projectIndex: https://developer.sovrn.com/llms.txt --- # Merchants By Date This endpoint is used to query aggregated performance metrics by Merchant and Date. This data can be used to see individual merchant performance by day, your top performing merchants, actualized earnings, and more, all in real-time. Metrics include Revenue, Clicks, Sales, Actions, Conversion Rate and EPC. > ❗️ Authorization > > To query this API, include a Secret Key in the Authorization header of your request. The value of the header must be formatted as `secret {SECRET_KEY}`, ensuring that the word `secret` is followed by a space before the key itself. > > For details on generating a Secret Key for your site, visit our [Authorization](https://developer.sovrn.com/docs/authorization) guide. > 🚧 Required Field > > Both `clickDateStart` and `clickDateEnd` are required for each API call. # Date Range > 📘 Date Range Limit > > 1 month (31 days) You will need to submit both `clickDateStart` and `clickDateEnd` with each call to the API in the format "yyyy-mm-dd" where yyyy is the four digit year, mm is the two digit month and dd is the two digit day. The supplied `clickDateEnd` is excluded from the range and functions similarly to a less-than operator. For example, if you would like to select the complete month of March, set `clickDateStart` to '2023-03-01' and `clickDateEnd` to '2023-04-01'. Additionally, if you would like to select a single day like March 1, 2023, set `clickDateStart` to '2023-03-01' and `clickDateEnd` to '2023-03-02'. This API is currently limited to return 1 month (31 days) of data per request. However, this limit will be increased in future updates. # Rate Limiting > 📘 API Rate Limit > > 1 request every 60 seconds You can make API requests at a rate of up to 1 request every 60 seconds. To adhere to this rate limit, include a delay of at least 60 seconds between consecutive calls. For example, if you need to make multiple requests for data across multiple months, ensure there is a minimum gap of 60 seconds between each request. # Filters You can filter the response by including one or more of the query parameters at the bottom of the page (with their respective data types). For an example of specifying multiple filters, see [`Example of multiple filters`](#section-example-of-multiple-filters) below. Note that some filters like `campaignIds` and `merchantGroupIds` can also take a comma separated list of numeric ID values. ## Campaigns You can filter the response by `campaignIds`, or by using multiple `campaignIds`. To filter by `campaignIds`, include the `campaignIds` parameter in the request, followed by the equal sign, followed by one or more `campaignIds`, separated by commas. For example: `campaignIds=1,2,3`. The `campaignIds` must only contain numeric values, greater than 0. See [`Example of filtering by multiple campaignIds`](#section-example-of-filtering-by-multiple-campaign-ids) below. To get a list of campaigns, or search for a specific campaign by `name`, visit our [Campaigns](https://developer.sovrn.com/reference/campaigns) reference guide. ## Merchants You can filter the response by `merchantGroupIds`, or by using multiple `merchantGroupIds`. To filter by `merchantGroupIds`, include the `merchantGroupIds` parameter in the request, followed by the equal sign, followed by one or more `merchantGroupIds`, separated by commas. For example: `merchantGroupIds=1,2,3`. The `merchantGroupIds` must only contain numeric values, greater than 0. To get a list of Merchant Group IDs, or search for a specific merchant by `name`, visit our [Merchant Status](https://developer.sovrn.com/reference/merchant-status-api) reference guide. Ensure that you utilize the `groupId` acquired through this API when making requests. ## Other Arguments ### `programType` | Accepted Arguments | Meaning | | :----------------- | :-------------- | | `CPA` | Cost per action | | `CPC` | Cost per click | ### `sovrnProduct` | Accepted Arguments | Meaning | | :----------------- | :----------------- | | `WRA` | Link | | `ORG` | JavaScript | | `RAC` | Click API | | `RAL` | Link API | | `CUP` | Coupon API | | `TPA` | Product API | | `PCR` | Price Comparison | | `TXT` | In-text | | `SHG` | Shopping Galleries | | `PRF` | Product Feed | | `INS` | Insert | | `UNK` | Unknown | ### `deviceType` | Accepted Arguments | Meaning | | :----------------- | :------ | | `DSK` | Desktop | | `MBL` | Mobile | | `TBL` | Tablet | | `UKN` | Unknown | ### `country` To filter by country, please use two-letter ISO [Country Codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements). # Examples You can use `CURL`, `Postman`, `Insomnia`, `Talend`, or your favorite REST API tool of choice, in order to make the `/reporting/transactions` request. Using `gzip` compression will compress the response, therefore making the response time quicker. Note that the response will always be in JSON format. A CURL example executed from the command line, using gzip compression and writing the response to a file named `commerce-merchant-reporting.json` would be: ``` curl --request GET --location 'https://viglink.io/v1/reports/merchantsbydate?clickDateStart=2023-01-01&clickDateEnd=2023-01-02' \ --header 'Authorization: secret ' \ --header 'Accept-Encoding: gzip' --compressed > commerce-merchant-reporting.json ``` #### Example without gzip compression: ``` curl --request GET --location 'https://viglink.io/v1/reports/merchantsbydate?clickDateStart=2023-01-01&clickDateEnd=2023-01-02' \ --header 'Authorization: secret ' > commerce-merchant-reporting.json ``` #### Example of multiple filters: ``` curl --request GET --location 'https://viglink.io/v1/reports/merchantsbydate?clickDateStart=2023-01-01&clickDateEnd=2023-01-02&campaignIds=100&merchantGroupIds=78910&programType=CPC' \ --header 'Authorization: secret ' \ --header 'Accept-Encoding: gzip' --compressed > commerce-merchant-reporting.json ``` #### Example of filtering by multiple `campaignIds`: ``` curl --request GET --location 'https://viglink.io/v1/reports/merchantsbydate?clickDateStart=2023-01-01&clickDateEnd=2023-01-02&campaignIds=100,200,300&merchantGroupIds=78910&programType=CPC' \ --header 'Authorization: secret ' \ --header 'Accept-Encoding: gzip' --compressed > commerce-merchant-reporting.json ``` #### Example of filtering by multiple `merchantGroupIds`: ``` curl --request GET --location 'https://viglink.io/v1/reports/merchantsbydate?clickDateStart=2023-01-01&clickDateEnd=2023-01-02&campaignIds=100&merchantGroupIds=70,80,90,100&programType=CPA' \ --header 'Authorization: secret ' \ --header 'Accept-Encoding: gzip' --compressed > commerce-merchant-reporting.json ``` # FAQ Q: deviceType is sometimes unknown, why?\ A: We don't always have access to detailed information about the click, or there may be instances where we are unable to accurately determine the device type. # OpenAPI definition ```json { "openapi": "3.0.3", "info": { "title": "Commerce Real-Time Reports", "description": "Transaction Reporting Service (TRS) provides Reporting APIs.", "termsOfService": "http://sovrn.io/terms/", "version": "20230630" }, "externalDocs": { "description": "Find out more Transaction Reporting Services", "url": "https://authcore.atlassian.net/l/cp/G5HL5km5" }, "security": [ { "bearerAuth": [] } ], "servers": [ { "url": "https://viglink.io/v1" } ], "paths": { "/reports/merchantsbydate": { "get": { "tags": [ "reports" ], "summary": "Merchants By Date", "description": "This endpoint is used to query aggregated performance metrics by Merchant and Date. This data can be used to see individual merchant performance by day, your top performing merchants, actualized earnings, and more, all in real-time. Metrics include Revenue, Clicks, Sales, Actions, Conversion Rate and EPC.", "parameters": [ { "name": "clickDateStart", "in": "query", "description": "Start Date", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "clickDateEnd", "in": "query", "description": "End Date", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "campaignIds", "in": "query", "description": "Comma separated list of campaign IDs", "required": false, "schema": { "type": "string", "pattern": "^[0-9,]+$" } }, { "name": "subIds", "in": "query", "description": "Comma separated list of Comma separated list of sub IDs", "required": false, "schema": { "type": "string" } }, { "name": "merchantGroupIds", "in": "query", "description": "Comma separated list of merchant group IDs", "required": false, "schema": { "type": "string", "pattern": "^[0-9,]+$" } }, { "name": "cuids", "in": "query", "description": "Comma separated list of CUIDs (custom tracking IDs)", "required": false, "style": "form", "schema": { "type": "string" } }, { "name": "pageUtmSource", "in": "query", "description": "Comma seperated list of page UTM sources", "required": false, "schema": { "type": "string" } }, { "name": "pageUtmMedium", "in": "query", "description": "Comma seperated list of page UTM mediums", "required": false, "schema": { "type": "string" } }, { "name": "pageUtmCampaign", "in": "query", "description": "Comma seperated list of page UTM campaings", "required": false, "schema": { "type": "string" } }, { "name": "pageUtmTerm", "in": "query", "description": "Comma seperated list of page UTM terms", "required": false, "schema": { "type": "string" } }, { "name": "pageUtmContent", "in": "query", "description": "Comma seperated list of page UTM contents", "required": false, "schema": { "type": "string" } }, { "name": "linkUtmSource", "in": "query", "description": "Comma seperated list of link UTM sources", "required": false, "schema": { "type": "string" } }, { "name": "linkUtmMedium", "in": "query", "description": "Comma seperated list of link UTM mediums", "required": false, "schema": { "type": "string" } }, { "name": "linkUtmCampaign", "in": "query", "description": "Comma seperated list of link UTM campaigns", "required": false, "schema": { "type": "string" } }, { "name": "linkUtmTerm", "in": "query", "description": "Comma seperated list of link UTM terms", "required": false, "schema": { "type": "string" } }, { "name": "linkUtmContent", "in": "query", "description": "Comma seperated list of link UTM contents", "required": false, "schema": { "type": "string" } }, { "name": "programType", "in": "query", "description": "Type of program (CPA/CPC)", "required": false, "schema": { "type": "string", "enum": [ "CPC", "CPA" ] } }, { "name": "sovrnProduct", "in": "query", "description": "Sovrn Product", "required": false, "schema": { "$ref": "#/components/schemas/SovrnProductModel" } }, { "name": "deviceType", "in": "query", "description": "Type of device", "required": false, "schema": { "$ref": "#/components/schemas/DeviceTypeModel" } }, { "name": "country", "in": "query", "description": "Two-letter ISO country code", "required": false, "schema": { "type": "string", "pattern": "^[A-Z]{2}$" } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantsByDateResponseModel" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Authorization information is missing or invalid" }, "404": { "description": "Merchant data not found" }, "5XX": { "description": "Unexpected error" } } } } }, "components": { "schemas": { "SovrnProductModel": { "type": "string", "enum": [ "UNK", "ORG", "INS", "WRA", "RAC", "RAL", "CUP", "TPA", "PCR", "TXT", "SHG", "PRF" ] }, "DeviceTypeModel": { "type": "string", "enum": [ "DSK", "MBL", "TBL", "UKN" ] }, "BaseResponseModel": { "type": "object", "properties": { "revenue": { "type": "number" }, "clicks": { "type": "number" }, "sales": { "type": "number" }, "actions": { "type": "number" }, "conversionRate": { "type": "number" }, "epc": { "type": "number" } } }, "MerchantsByDateResponseModel": { "type": "object", "description": "TSR Merchants By Date response model", "properties": { "data": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/BaseResponseModel" }, { "type": "object", "properties": { "date": { "type": "string" }, "merchantGroupId": { "type": "integer", "format": "int64" }, "merchantGroupName": { "type": "string" } } } ] } }, "totals": { "type": "object", "properties": { "revenueTotal": { "type": "number" }, "clicksTotal": { "type": "number" }, "salesTotal": { "type": "number" }, "actionsTotal": { "type": "number" }, "conversionRateTotal": { "type": "number" }, "epcTotal": { "type": "number" }, "merchantGroupIdsTotal": { "type": "number" }, "merchantGroupNameTotal": { "type": "number" } } } } } }, "securitySchemes": { "bearerAuth": { "type": "apiKey", "name": "authorization", "in": "header" } } }, "x-readme": { "explorer-enabled": true, "proxy-enabled": true } } ```