This endpoint retrieves only the updated merchants since your last query, including geo-specific rates and performance metrics.
Authorization
In order to query this API you will need to use a Secret Key in the Authorization header of the request. To learn more about generating a Secret Key for your site, visit our Authorization guide.
Required Field
To use this endpoint, the following parameters are required:
campaignId
: Specifies the campaign context for retrieving merchant data. This parameter is mandatory for all requests. Refer to our Campaigns guide for information on obtaining or searching for a campaignId.
since
orIf-None-Match
: To retrieve merchants that have been , you must include either:
since
: A timestamp (ISO 8601) to fetch merchants updated after a specific date and timeIf-None-Match
: An ETag header from a prior response to fetch only data modified since that request.Note: You must provide either
since
orIf-None-Match
in each request to ensure accurate delta retrieval; omitting both will result in an error.
Rate Limiting
API Rate Limit
1 request every 10 seconds
Requests are limited to 1 request every 10 seconds. Exceeding this rate limit can result in your API key being temporarily blocked or throttled.
To adhere to this rate limit:
- Include a delay of at least 10 seconds between consecutive API calls.
- If you need to make multiple requests (e.g., when paginating through results), ensure there is a minimum gap of 10 seconds between each request or that the previous request has completed before making another one.
Pagination
The API supports pagination to control the number of results returned in a single response. You can specify the page number and the number of results per page using the page and pageSize fields in the request body.
page
: The page number to retrieve (starting from 1).pageSize
: The number of results to return per page. The maximum allowed value is 2500, and the default value is 1000.
Example Request:
Example Request:
{
"filters": [
{
"type": "GROUP_ID",
"values": ["384"]
}
],
"page": 1,
"pageSize": 1000
}
Pagination Fields in the Response:
page
: The current page number.perPage
: The number of results per page (as specified in the request).totalItems
: The total number of items that match the filters.
Example Response:
{
"results": [
// Array of merchant summaries
],
"page": 1,
"perPage": 1000,
"totalItems": 5000
}