Partner API

Requesting ads for future dates

Using CitrusAd's campaignFilterDate property, you are able to query for campaigns that will be live on the date requested.

📘

This feature is best for banner ad integrations, especially if you have a legal requirement to show any pricing information in the banner at the time of a customer's delivery slot selection.

What does this do?

When you specify a campaignFilterDate in your ad request to CitrusAd, we'll only look at campaigns that will be active on the date you've specified, or campaigns that are set to "Always On" in the CitrusAd system.

In the CitrusAd system, advertisers can set a campaign to only be active across certain date ranges.

This is typically up to the advertiser if they wish to schedule their campaign over a specific time frame, or they can also select "Always On" to allow the campaign to always spend if there is budget available.

For example, the campaign above will be active between 07/02/2023, and 14/03/2023. If a relevant ad request is received with a campaignFilterDate between these two dates, the campaign will be served if it is deemed the most relevant ad.

Integration requirements

High level overview

In addition to a standard integration with CitrusAd, your integration will need to be enhanced to specify a campaignFilterDate in your ad request. No changes are needed to impression and click reporting, and you must ensure your order reporting is correct as outlined below.

Ad request

Your ad request will need to specify a campaignFilterDate, in ISO-8601 format, an example is below:

This campaignFilterDate will be the date at which the customer will be receiving their order from your website.

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "customerId": "wertg5432a",
    "placement": "search",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "searchTerm": "chocolate",
    "campaignFilterDate": "2022-11-20T13:40:00+01:00",
    "options": {
                         "filterMode": "AndOr",
                             },
    "maxNumberOfAds": 3    
}

Order reporting

When reporting orders, you will need to ensure the below are implemented:

  • the order date you specify should be the time the customer checked out, and not the time the customer's order will be collected/delivered.
    • This is to ensure CitrusAd's attribution algorithm can apply the correct look-back window to your customer's interactions to attribute sales to campaigns that have been shown to the customer.
  • As it is likely a customer will re-submit their orders, you will also need to ensure you are not sending an order ID to CitrusAd. This will ensure when re-submitting orders and order updates, the CitrusAd algorithm reviews the order and attributes accordingly.
    • Currently, the CitrusAd attribution algorithm does not re-process an order when it is submitted with an order ID that has been submitted previously.

Please review Order data for the correct information regarding reporting orders.

Platform reporting

As the CitrusAd system displays reporting in real-time, clicks and impressions, including those for future deliveries will be reported when they are viewed or clicked.

As ads are being served in real-time, wallets will be charges as impressions and clicks are reported to CitrusAd.

🚧

Spend reporting

As this feature queries for campaigns in the future, you may see campaigns with active dates in the future with spend and reporting data accruing, this is the intended behaviour of the feature as campaigns that are planned to be active over a future period are being queried for in advance.