API overview

How does CitrusAd work?

The CitrusAd API is organised around REST. The API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. The API uses built-in HTTP features including HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients.

Authentication to the CitrusAd API is managed through the use of API keys. API keys are used during communication between your backend and the CitrusAd API.

The CitrusAd API supports the upload of products, catalogs, customers, and order data, which is used to generate ads. You can use the CitrusAd API to request ads and report on interactions with those ads.

CitrusAd endpoints

CitrusAd uses various endpoints to sync data and generate ads. A brief summary is provided below:

catalogsSyncing catalogs via APIUsed to create catalogs via API. For single catalog namespaces, this is something your Technical Account Manager can organise for you.
catalog-productsSyncing products via APIUsed to create and update product data within a catalog.
customersSyncing customer data via APIUsed to create and update customer data within a catalog.
ordersSyncing order data via APIUsed to send order data to CitrusAd.
/resource/Reporting clicks & impressions , Syncing order data via APIUsed to report clicks and impressions, as well as orders if reporting via front-end.
/ads/generateGenerating adsUsed to generate product ads and banner ads.
/ads/bannerxGenerating adsUsed to generate banner x ads.


You don’t need to use endpoints for catalog, product, customer, and order syncing. CitrusAd supports syncing data via file, which may be suitable for your requirements.

Content type & payload

The data payload is in JSON format. The Content-Type for these endpoints is application/json, which should be passed as a header in your requests as follows:

-H "Content-Type: application/json" \

Authenticating requests

Basic authentication

All integration resources use basic authentication which should be passed as a header with your API key as follows:

-H "Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8" \

Your API Key can be accessed in the Integration Settings section of the retailer team. You will only need the secret API key.

OAuth2.0 authentication

CitrusAd's ad generation endpoint is additionally compatible with OAuth2.0. Review OAuth 2.0 Authentication for more information.

Base URLs

CitrusAd uses different base URLs for staging and production environments.


To receive your staging base URL, please contact CitrusAd. Once your integration is in progress, we will provide you with production base URLs.