## 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 ```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 ```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 ```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 ```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 ```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 ```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 ```json { "data": { "type": "CouponPreview", "attributes": { "previewHtml": " " } }, "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](https://help.criteo.com/kb/guide/en/image-ads-8hXUBDeeoo/Steps/775688) **`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](https://help.criteo.com/kb/guide/en/third-party-ads-QUSq5Astwy/Steps/775787,817360) **`invalid-creative-request`** Invalid request on the Creative endpoint. **`invalid-ad-request`** Invalid request on the Ad endpoint.