Coupon - Criteo Docs
Search Coupon
Retrieving Coupons for a Specific Advertiser
Coupons created through Criteo’s API will be returned for the designated advertiser ID. Only coupons created through API and Commerce Growth are returned. The API will return an array of the IDs, name, description (if specified), ad set ID, landing page URL, format, start date, and end date (if specified) for the specified advertiser ID. Please note that the advertiser ID is required in the request URL. The offset and limit are optionals.
offset
0 based index of the first coupon to return in the response. The default is 0.
limit
The number of coupons to be returned. The default is 50.
Response example:
JSON
{
"data": [
{
"type": "Coupon",
"id": "18",
"attributes": {
"name": "My first coupon",
"description": "Description of my first coupon",
"author": "r.deckard",
"advertiserId": "51",
"adSetId": "345",
"landingPageUrl": "https://my-landing-page.com",
"startDate": "2021-11-23T18:25:43.511Z",
"format": "LogoZone",
"status": "Live",
"images": [
{
"width": 300,
"height": 250,
"slideUrls": ["https://static.criteo.net/image_1.jpg"]
},
{
"width": 130,
"height": 90,
"slideUrls": ["https://static.criteo.net/image_2.jpg"]
}
],
"showEvery": 3,
"showDuration": 3,
"rotationsNumber": 2,
"id": "18"
}
},
{
"type": "Coupon",
"id": "19",
"attributes": {
"name": "My second Coupon",
"description": "Description of my second coupon",
"author": "r.deckard",
"advertiserId": "51",
"adSetId": "502",
"landingPageUrl": "https://my-landing-page.com",
"startDate": "2021-12-19T18:25:43.511Z",
"endDate": "2022-01-01T10:00:00.511Z",
"format": "FullFrame",
"status": "Live",
"images": [
{
"width": 300,
"height": 250,
"slideUrls": ["https://static.criteo.net/image_1.jpg", "https://static.criteo.net/another-imagejpg"]
},
{
"width": 120,
"height": 600,
"slideUrls": ["https://static.criteo.net/image_2.jpg", "https://static.criteo.net/alternative-image.jpg"]
}
],
"showEvery": 1,
"showDuration": 1,
"rotationsNumber": 3,
"id": "19"
}
}
],
"errors": [],
"warnings": []
}
Retrieving a Specific Coupon
Coupon created through Criteo’s API will be returned for the designated coupon ID. The API will return an array of the ID, type, and coupon specific attributes for the specified coupon ID. Please note that the advertiser ID and coupon ID are required in the request URL.
Response example:
JSON
{
"data": {
"type": "Coupon",
"id": "18",
"attributes": {
"name": "My first coupon",
"description": "Description of my first coupon",
"author": "r.deckard",
"advertiserId": "51",
"adSetId": "345",
"landingPageUrl": "https://my-landing-page.com",
"startDate": "2021-11-23T18:25:43.511Z",
"format": "LogoZone",
"images": [
{
"width": 300,
"height": 250,
"slideUrls": ["https://static.criteo.net/image_1.jpg"]
},
{
"width": 130,
"height": 90,
"slideUrls": ["https://static.criteo.net/image_2.jpg"]
}
],
"showEvery": 3,
"showDuration": 3,
"rotationsNumber": 2
}
},
"errors": [],
"warnings": []
}
Get the list of Coupons supported sizes
Supported sizes for the coupons will be returned for the designated ad set ID. The API will return an array of the supported sizes by format (LogoZone and FullFrame) for the specified ad set ID. Please note that the advertiser ID and adset ID are required in the request URL.
Response example:
JSON
{
"data": {
"type": "CouponSupportedSizes",
"attributes": {
"logoZone": [
"300x40",
"130x90",
"300x54",
"105x50"
],
"fullFrame": [
"300x250",
"160x600",
"728x90",
"300x600"
],
"id": null
},
"errors": [],
"warnings": []
}
Creating A New Coupon
A new coupon can be created for a specific advertiser by making a POST call to the coupons’ endpoint.
The request body should specify the name, ad set ID, description (optional), and the coupon attributes.
Coupon Attributes
landingPageUrl
Web redirection of the landing page url.
startDate
The date when the Coupon will be launched.
endDate
The date when the coupon will stop being displayed. If the end date is not specified (i.e., null), the coupon will always be displayed.
format
Format of the coupon. Can be FullFrame or LogoZone.
images
List of slides images.
showEvery
Show the coupon every N seconds. Can be between 1 and 10.
showDuration
Show coupon for a duration of N seconds. Can be between 1 and 5.
rotationsNumber
Number of rotations for the coupons. The number can be between 1 and 10.
Request example:
JSON
{
"data": {
"type": "CreateCouponRequest",
"attributes": {
"name": "New coupon",
"adSetId": "345",
"description": "Description of my new coupon",
"landingPageUrl": "https://my-landing-page.com",
"startDate": "2021-11-25T18:25:43.511Z",
"format": "FullFrame",
"images": [
{
"width": 300,
"height": 250,
"slideBase64Strings": [
"{base 64 encoded image string}",
"{another base 64 encoded image string}"
]
}
],
"showEvery": 1,
"showDuration": 1,
"rotationsNumber": 1
}
}
}
The API will return an array of the name, ad set ID, description (optional), and the coupon attributes of the new coupon. Please note that the advertiser ID is required in the request URL.
Response example:
JSON
{
"data": {
"type": "Coupon",
"id": "18",
"attributes": {
"name": "New coupon",
"description": "Description of my new coupon",
"author": "r.deckard",
"advertiserId": "510",
"adSetId": "345",
"landingPageUrl": "https://my-landing-page.com",
"startDate": "2021-11-24T18:25:43.511Z",
"format": "FullFrame",
"images": [
{
"width": 300,
"height": 250,
"slideUrls": [
"https://static.criteo.net/image.jpg",
"https://static.criteo.net/image-2.jpg"
]
}
],
"showEvery": 1,
"showDuration": 1,
"rotationsNumber": 1,
"id": "18"
}
},
"errors": [],
"warnings": []
}
Updating a Coupon
The coupon start date and end date can be updated by making a PUT request to the coupons’ endpoint with a specific coupon ID and advertiser ID in the URL path.
Request example:
JSON
{
"data": {
"type": "UpdateCouponRequest",
"attributes": {
"startDate": "2024-06-25T18:25:43.511Z"
}
}
}
Deleting a coupon
A coupon can be deleted by specifying the coupon ID and advertiser ID in the URL path of a DELETE call to the coupons’ endpoint. The API will return an array with the coupon ID that was deleted.
Preview a coupon
Coupon can be previewed for the designated coupon ID. The API will return an array of the coupon HTML preview for the specified coupon ID. Please note that the advertiser ID and coupon ID are required in the request URL.
Response example:
JSON
{
"data": {
"type": "CouponPreview",
"attributes": {
"previewHtml": "<html> <!-- content of coupon html preview--> </html>"
}
},
"errors": [],
"warnings": []
}
Validation Errors
user-request-forbidden-advertiser
The user doesn’t have the permission to access the specified advertiser.
user-request-forbidden-creative
The user doesn’t have the permission to access the specified creative.
user-request-forbidden-ad
The user doesn’t have the permission to access the specified ad.
invalid-action-with-managed-creative
The action cannot be performed on a managed service creative.
invalid-action-with-managed-ad
The action cannot be performed on a managed service ad.
invalid-creative-action-with-status
The action cannot be performed due to the status of the creative.
invalid-image
One of the images provided is invalid. Please check the image requirements here
invalid-redirection-url-image
The redirection URL specified doesn’t match the advertiser domain.
invalid-html-tag
One of the HTML tags is not supported. Please check the list of supported ad servers here
invalid-creative-request
Invalid request on the Creative endpoint.
invalid-ad-request
Invalid request on the Ad endpoint.