> ## Documentation Index
> Fetch the complete documentation index at: https://developers.criteo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Coupon

export const EndpointBadge = ({method = "GET", children}) => {
  const METHOD_STYLES = {
    GET: {
      bg: "mint-bg-[#2AB673]"
    },
    POST: {
      bg: "mint-bg-[#3064E3]"
    },
    PUT: {
      bg: "mint-bg-[#C28C30]"
    },
    PATCH: {
      bg: "mint-bg-[#DA622B]"
    },
    DELETE: {
      bg: "mint-bg-[#CB3A32]"
    },
    API: {
      bg: "mint-bg-black"
    }
  };
  const key = method.toUpperCase();
  const styles = METHOD_STYLES[key] ?? METHOD_STYLES.API;
  return <div className="relative mt-7">
      <span className={`absolute -top-2 -left-2 z-10 ${styles.bg} text-white px-2.5 py-0.5 rounded-full text-xs font-bold tracking-wide`}>
        {key}
      </span>
      {children}
    </div>;
};

## **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.

<EndpointBadge method="get">
  ```http theme={null}
  /advertisers/{advertiserId}/coupons
  ```
</EndpointBadge>

 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 expandable theme={null}
{
  "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.

<EndpointBadge method="get">
  ```http theme={null}
  /advertisers/{advertiserId}/coupons/{couponId}
  ```
</EndpointBadge>

 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 expandable theme={null}
{
  "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 ad set ID.

<EndpointBadge method="get">
  ```http theme={null}
  /advertisers/{advertiserId}/coupons-supported-sizes
  ```
</EndpointBadge>

 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.

**Response example:**

```json JSON theme={null}
{
  "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, 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.

<EndpointBadge method="post">
  ```http theme={null}
  /advertisers/{advertiserId}/coupons
  ```
</EndpointBadge>

**Request example:**

```json JSON theme={null}
{
  "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 expandable theme={null}
{
  "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.

<EndpointBadge method="put">
  ```http theme={null}
  /advertisers/{advertiserId}/coupons/{couponId}
  ```
</EndpointBadge>

**Request example:**

```json JSON theme={null}
{
  "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.

<EndpointBadge method="delete">
  ```http theme={null}
  /advertisers/{advertiserId}/coupons/{couponId}
  ```
</EndpointBadge>

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

<EndpointBadge method="get">
  ```http theme={null}
  /advertisers/{advertiserId}/coupons/{couponId}/preview
  ```
</EndpointBadge>

 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 theme={null}
{
  "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](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.