Coupon

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.

/advertisers/{advertiserId}/coupons?offset=0&limit=30

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.

{
  "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": [ ]  /* omitted if no errors */
	"warnings": [ ]   /* omitted if no warnings */
}

Retrieving a Specific Coupon

Coupon created through Criteo's API will be returned for the designated coupon ID.

/advertisers/{advertiserId}/coupons/{couponId}

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.

{
  "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": [ ],  /* omitted if no errors */
    "warnings": [ ]   /* omitted if no warnings */
}

Get the list of Coupons supported sizes

Supported sized for the coupons will be returned for the designated adset ID.

/advertisers/{advertiserId}/coupons-supported-sizes?ad-set-id={adsetId}

The API will return an array of the supported sizes by format (LogoZone and FullFrame) for the specified adset ID. Please note that the advertiser ID and adset ID are required in the request URL.

{
  "data": {
      "type": "CouponSupportedSizes",
      "attributes": {
			"logoZone": [
				"300x40",
				"130x90",
				"300x54	",
				"105x50",
				...
			],
			"fullFrame": [
				"300x250",
				"160x600",
				"728x90",
				"300x600",
				 ...
			],
      "id": null
    },
    "errors": [	], /* omitted if no errors */
    "warnings": [ ]	/* omitted if no 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, adset 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 fo the coupons. Can be between 1 to 10.

/advertisers/{advertiserId}/coupons

{
  "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 the name, adset id, description (optional) and the coupon attributes of the new coupon. Please note that the advertiser ID is required in the request URL.

{
  "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": [	], /* omitted if no errors */
  "warnings": [ ] /* omitted if no errors */
}

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.

/advertisers/{advertiserId}/coupons/{couponId}

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

/advertisers/{advertiserId}/coupons/{couponId}

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

/advertisers/{advertiserId}/coupons/{couponId}/preview

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.

{
  "data": {
      "type": "CouponPreview",
      "attributes": {
        	"previewHtml": "<html> <!-- content of coupon html preview--> </html>"
      }
    },
    "errors": [ ],	/* omitted if no errors */
    "warnings": [	]/* omitted if no 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.