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

# Campaign

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>;
};

## **Campaign Example**

The following is an example of the JSON data structure of an Campaign.

Additional details about the individual attributes of Campaigns can be found below.

```json Example Campaign theme={null}
{
    "type": "Campaign",
    "attributes": {
        "name": "My Campaign",
        "advertiserId": 12345,
        "goal": "Retention",
        "spendLimit": {
            "spendLimitRenewal": "daily",
            "spendLimitType": "capped",
            "spendLimitAmount": 123.45
        }
    }
}
```

 

## **Campaign Attributes**

**`name`**\
Currently read-only. The Campaign name, set by the advertiser.

 

**`advertiserId`**\
Read-only. The advertiser associated with the Campaign.

 

**`goal`**\
The marketing goal of the Campaign. Can be `Acquisition`, `Retention` or `Unspecified` (only for older campaigns).

 

**`spendLimit.spendLimitRenewal`**\
The cadence of spend limit renewal. Can be `daily`, `monthly`, `lifetime`, or `undefined` in the case of an `uncapped` limit type.

 

**`spendLimit.spendLimitType`**\
Whether the Campaign spend is capped or not. Can be `capped` or `uncapped`.

 

**`spendLimit.spendLimitAmount`**\
A decimal value representing the spend limit for the Campaign. If `spendLimitType` is `uncapped`, the value will be `null`.

 

## **Create a campaign**

A new campaign can be created for a specific advertiser by making a POST call to the campaigns endpoint. The request body should specify the type (`Campaign`) and the [campaign attributes](/marketing-solutions/v2025.10/docs/campaign#campaign-attributes).

 

<Info>
  **Spend Limit**

  `spendLimitRenewal` and `spendLimitAmount` are only relevant when `spendLimitType` is set to capped.
</Info>

 

 

<Info>
  **Goal**

  The field `goal` is mandatory and can be either `Acquisition` or `Retention`.
</Info>

<EndpointBadge method="post">
  ```http theme={null}
  /marketing-solutions/campaigns
  ```
</EndpointBadge>

<CodeGroup>
  ```json Sample Request Body theme={null}
  {
    "data":
  	{
      "type": "Campaign",
      "id": "99999",
       
      "attributes": {
          "name": "My Campaign",
          "advertiserId": 12345,
          "goal": "Retention",
          "spendLimit": {
              "spendLimitRenewal": "daily",
              "spendLimitType": "capped",
              "spendLimitAmount": 123.45
          }
     }
  }
  ```
</CodeGroup>

The API will return an array of the ID, the type (`Campaign`) and the campaign attributes of the new campaign.

```json theme={null}
{
  "data": {
    "id": "99999",
    "type": "Campaign",
    "attributes": {
      "name": "My Campaign",
      "advertiserId": "12345",
      "spendLimit": {
        "spendLimitType": "capped",
        "spendLimitRenewal": "daily",
        "spendLimitAmount": 123.45
      },
      "goal": "Retention"
    }
  },
  "warnings": [],
  "errors": []
}
```

## **Searching Campaigns**

### Retrieving Campaigns by Filtering

Campaigns can be retrieved by specifying filters to apply to the set of all Campaigns in your portfolio.

Using filters, you can restrict the returned results to particular `advertiserIds` or specific `campaignIds`. Filters can be combined.

For example, to retrieve the Campaigns in your portfolio related to a particular advertiser, filter by `advertiserIds`:

<EndpointBadge method="post">
  ```http theme={null}
  /marketing-solutions/campaigns/search
  ```
</EndpointBadge>

<CodeGroup>
  ```json JSON Payload theme={null}
  {
      "filters": {
          "advertiserIds": [ "12345" ]
      }
  }
  ```
</CodeGroup>

The API will return an array of Campaigns that match the provided filters:

```json Sample Response theme={null}
{
    "data": [
        {
            "type": "Campaign",
            "id": "99999",
            "attributes": {
               "name": "My Campaign",
               "advertiserId": 12345,
               "goal": "Retention",
               "spendLimit": {
                    "spendLimitRenewal": "daily",
                    "spendLimitType": "capped",
                    "spendLimitAmount": 123.45
                }
            }
        }
    ],
    "errors": []
}
```

 

 

### Retrieving All Campaigns

When no filters are specified in the JSON payload, all Campaigns in your portfolio will be returned, as in the example below:

<EndpointBadge method="post">
  ```http theme={null}
  /marketing-solutions/campaigns/search
  ```
</EndpointBadge>

<CodeGroup>
  ```json JSON Payload theme={null}
  {
      "filters": {}
  }
  ```
</CodeGroup>

 

 

### Retrieving One Specific Campaign

You can also fetch the details for a single Campaign using a GET request:

<EndpointBadge method="get">
  ```http theme={null}
  /marketing-solutions/campaigns/{campaignId}
  ```
</EndpointBadge>

 

The response `data` will be a single object containing the Campaign details.

```json Sample Response theme={null}
{
    "data": {
        "type": "Campaign",
        "id": "99999",
        "attributes": { ... }
    },
    "errors": []
}
```

 

## **Update Campaigns**

The fields of one or more Campaigns can be updated by making a `PATCH` call to the Campaigns endpoint. The payload should be an array of partial or whole Campaigns, each specifying the fields to be modified.

For example, the following call would update the `spendLimit` settings of an existing Campaign:

<EndpointBadge method="patch">
  ```http theme={null}
  /marketing-solutions/campaigns
  ```
</EndpointBadge>

<CodeGroup>
  ```json Sample Request Body theme={null}
  {
      "data": [
          {
              "type": "Campaign",
              "id": "99999",
              "attributes": {
                  "spendLimit": {
                      "spendLimitRenewal": "daily",
                      "spendLimitType": "capped",
                      "spendLimitAmount": 123.45
                  }
              }
          }
      ]
  }
  ```
</CodeGroup>

The API will return an array of Campaigns that have been updated successfully in the response `data`. These will contain only two parameters, `type` and `id`.

```json Sample Response theme={null}
{
    "data": [
        {
            "type": "Campaign",
            "id": "99999"
        }
    ],
    "errors": [],
    "warnings": []
}
```

 

 

## **Partial Success / Partial Failure**

Each Campaign update is processed individually and can succeed or fail without impacting other updates in the same payload.

As a result, those Campaign updates processed successfully will be returned in the `data` array of the response, while Campaign updates that have failed will return as an entry in the `errors` array of the response.

<Warning>
  **HTTP Response Codes**

  As a result of this individual processing, the API may respond with a `200` HTTP response code, but the result of its processing may have one or more failures.
</Warning>

 

 

For instance, for this payload which intends to update two Campaigns:

<EndpointBadge method="patch">
  ```http theme={null}
  /marketing-solutions/campaigns
  ```
</EndpointBadge>

<CodeGroup>
  ```json Sample Request Body theme={null}
  {
      "data": [
          {
              "type": "Campaign",
              "id": "99999",
              "attributes": {
                  "spendLimit": {
                      "spendLimitRenewal": "daily",
                      "spendLimitType": "capped",
                      "spendLimitAmount": 123.5
                  }
              }
          },
          {
              "type": "Campaign",
              "id": "88888",
              "attributes": {
                  "spendLimit": {
                      "spendLimitRenewal": "daily",
                      "spendLimitType": "capped",
                      "spendLimitAmount": -9000
                  }
              }
          }
      ]
  }
  ```
</CodeGroup>

 

The response might look like:

```json Sample Response theme={null}
{
    "data": [
        {
            "type": "Campaign",
            "id": "99999"
        }
    ],
    "errors": [
        {
            "traceIdentifier": "56ed4096-f96a-4944-8881-05468efe0ec8",
            "type": "validation",
            "code": "campaign--campaign-update-check--validation-failed-on-spend-limit",
            "instance": "@data/1",
            "title": "Validation failed on spend limit",
            "detail": "There was an issue with the spend limit value specified."
        }
    ],
    "warnings": []
}
```

<Info>
  **Error `instance`**

  The `instance` field for validation errors will specify the index of the related update, beginning with index 0. For the example above, `@data/1` refers to the second requested update in the request's `data` array.
</Info>

A full list of error codes can be found on the [Validation Errors](/marketing-solutions/v2025.10/docs/campaign#validation-errors-and-warnings) page at the end of this section.\
In addition to [general API errors](/marketing-solutions/v2025.10/docs/api-error-types) , you may encounter validation errors when updating a Campaign.

Below is a list of error codes for Campaign validation and a more detailed description of their meaning.

 

## **Validation Errors and Warnings**

**Campaign Update Errors:**\
**`campaign--campaign-update-check--spend-limit-does-not-exist`**\
An update to spend limit was attempted on a Campaign which does not have a spend limit (e.g. an uncapped Campaign). Alternatively, the requestor may not have permissions to update the spend limit of the Campaign.

**`campaign--campaign-update-check--cannot-decrease-lifetime-spend-limit-below-what-is-already-spent`**\
An update attempted to decrease a *lifetime* spend limit of a Campaign to a value lower than what has already been spent.

**`campaign--campaign-update-check--validation-failed-on-spend-limit`**\
TK

**`campaign--campaign-update-check--cannot-update-same-campaign-multiple-times`**\
The Campaign is included multiple times in the same update payload. All Campaign field updates should be consolidated into one array item.

**`campaign--campaign-update-check--unavailable-feature-for-this-advertiser`**\
TK

 

**Campaign Update Warnings:**\
**`campaign--campaign-update-check--new-spend-limit-amount-will-take-place-at-the-next-period-start`**\
The update to spend limit was processed, but it will not take effect until the next period specified by `spendLimitRenewal` (e.g. the next day). This is typically because the new spend amount specified is lower than the amount already spent in the current period.