❗️

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 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.

sinceorIf-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 time
• If-None-Match: An ETag header from a prior response to fetch only data modified since that request.

Note: You must provide either since or If-None-Matchin 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:

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
}