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

# Budget Overrides

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

This feature provides more flexibility that allow advertisers to override a line-item budget for specific days or months.

You can set a monthly/daily budget override to temporarily spend more or less than the current monthly/daily budget for the months you specify. The override will take effect at midnight in your time zone on the first day of the month or first day of the range you select.

## **Endpoints**

| Verb  | Endpoint                                              | Description                                                                                                                               |
| ----- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `GET` | `/campaigns/{campaignId}/campaign-budget-overrides`   | Retrieves all existing budget overrides at the campaign level.                                                                            |
| `PUT` | `/campaigns/{campaignId}/campaign-budget-overrides`   | Replaces all existing campaign budget override settings. Use this endpoint can be used to add/remove or update existing budget overrides. |
| `GET` | `/line-items/{lineItemId}/line-item-budget-overrides` | Retrieves all existing budget overrides at the line-item level.                                                                           |
| `PUT` | `/line-items/{lineItemId}/line-item-budget-override`  | Replaces all existing line-item budget override settings. Use this endpoint to add/remove or update existing budget overrides.            |

 

## **Budget Override Attributes**

<ResponseField name="dailyLineItemBudgetOverrides">
  **Data Type:** object array

  **Description:** Line item budget override monthly part, chronological order restricted.
</ResponseField>

<ResponseField name="dailyLineItemBudgetOverrides">
  **Data Type:** object array

  **Description:** Line item budget override daily part, chronological order restricted.
</ResponseField>

<ResponseField name="startMonth">
  **Data Type:** string (date-time)

  **Description:** Monthly budget override start month, format `yyyy-MM`. If it is null, the StartMonth would be the following month of the last item in the override sequence.
</ResponseField>

<ResponseField name="startDate">
  **Data Type:** string (date-time)

  **Description:** Daily budget override start date, format `yyyy-MM-dd`. If it is null, the StartDate would be the following date of the last item in the override sequence.
</ResponseField>

<ResponseField name="duration">
  **Data Type:** string

  **Description:** The number of **months** (monthly Budget Override) or **days** (daily budget override) that the override is active from StartMonth (monthly budget override) or Start (daily budget override)

  **Examples**

  1. Monthly Override: "1M". Must end with 'M' or 'm'

  2. Daily Override: "1D". Must end with 'D' or 'd'
</ResponseField>

<ResponseField name="maxMonthlySpend">
  **Data Type:** number (double)

  **Description:** Monthly budget override maximum monthly spend amount.
</ResponseField>

<ResponseField name="maxDailySpend">
  **Data Type:** number (double)

  **Description:** Daily budget override maximum daily spend amount.
</ResponseField>

<ResponseField name="status">
  **Data Type:** string

  **Description:** Monthly or daily budget override computed status.
</ResponseField>

## **Campaigns**

### Get Campaign Budget Override

<EndpointBadge method="get">
  ```http theme={null}
  https://api.criteo.com/{version}/retail-media/campaigns/{campaignId}/campaign-budget-overrides
  ```
</EndpointBadge>

**Sample Request**

<CodeGroup>
  ```bash Bash theme={null}
  # Request
  curl -L 'https://api.criteo.com/{version}/retail-media/campaigns/446397494514737152/campaign-budget-overrides' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <MY_ACCESS_TOKEN>'
  ```
</CodeGroup>

**Sample Response**

<CodeGroup>
  ```json JSON expandable theme={null}
  {
      "data": {
          "type": "CampaignBudgetOverrides",
          "attributes": {
              "monthlyBudgetOverrides": [
                  {
                      "startMonth": "2023-12",
                      "duration": "1M",
                      "maxMonthlySpend": 100.00,
                      "status": "Expired"
                  },
                  {
                      "duration": "1M",
                      "maxMonthlySpend": 200.00,
                      "status": "Active"
                  },
                  {
                      "startMonth": "2024-03",
                      "duration": "1M",
                      "maxMonthlySpend": 150.00,
                      "status": "Upcoming"
                  }
              ],
              "dailyBudgetOverrides": [
                  {
                      "startDate": "2023-12-01",
                      "duration": "10D",
                      "maxDailySpend": 50.00,
                      "status": "Expired"
                  }
              ]
          }
      },
      "warnings": [],
      "errors": []
  }
  ```
</CodeGroup>

### Update Campaign Budget Override

<EndpointBadge method="put">
  ```http theme={null}
  https://api.criteo.com/{version}/retail-media/campaigns/{campaignId}/campaign-budget-overrides
  ```
</EndpointBadge>

**Sample Request**

<CodeGroup>
  ```bash Bash expandable theme={null}
  # Request
  curl -L -X PUT 'https://api.criteo.com/{version}/retail-media/campaigns/446397494514737152/campaign-budget-overrides' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <MY_ACCESS_TOKEN>' \
  -d '{
    "data": {
      "type": "UpdateBudgetOverride",
      "attributes": {
        "dailyBudgetOverrides": [
          {
            "duration": "15d",
            "maxDailySpend": "1",
            "startDate": "2024-01-01",
            "status": "Active"
          },
          {
            "duration": "15d",
            "maxDailySpend": "2",
            "startDate": "2024-01-16",
            "status": "Active"
          }
        ],
        "monthlyBudgetOverrides": [
          {
            "duration": "1M",
            "maxMonthlySpend": "10",
            "startMonth": "2024-01",
            "status": "Active"
          }
        ]
      }
    }
  }'
  ```
</CodeGroup>

**Sample Response**

<CodeGroup>
  ```json JSON theme={null}
  {
      "data": {
          "type": "CampaignBudgetOverrides",
          "attributes": {
              "monthlyBudgetOverrides": [
                  {
                      "startMonth": "2024-01",
                      "duration": "1M",
                      "maxMonthlySpend": 10.00,
                      "status": "Active"
                  }
              ],
              "dailyBudgetOverrides": [
                  {
                      "startDate": "2024-01-01",
                      "duration": "15D",
                      "maxDailySpend": 1.00,
                      "status": "Active"
                  },
                  {
                      "duration": "15D",
                      "maxDailySpend": 2.00,
                      "status": "Upcoming"
                  }
              ]
          }
      },
      "warnings": [],
      "errors": []
  }
  ```
</CodeGroup>

## **Line-items**

### Get Line Item Budget Override

Retrieves all existing budget overrides

<EndpointBadge method="get">
  ```http theme={null}
  https://api.criteo.com/{version}/retail-media/line-items/{lineItemId}/line-item-budget-overrides
  ```
</EndpointBadge>

**Sample Request**

<CodeGroup>
  ```bash Bash theme={null}
  # Request
  curl -L 'https://api.criteo.com/{version}/retail-media/line-items/446397611671216128/line-item-budget-overrides' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <MY_ACCESS_TOKEN>'
  ```
</CodeGroup>

**Sample Response**

<CodeGroup>
  ```json JSON expandable theme={null}
  {
      "data": {
          "type": "LineItemBudgetOverrides",
          "attributes": {
              "monthlyLineItemBudgetOverrides": [
                  {
                      "startMonth": "2023-12",
                      "duration": "2M",
                      "maxMonthlySpend": 100.00,
                      "status": "Upcoming"
                  }
              ],
              "dailyLineItemBudgetOverrides": [
                  {
                      "startDate": "2023-07-13",
                      "duration": "19D",
                      "maxDailySpend": 10.00,
                      "status": "Expired"
                  },
                  {
                      "startDate": "2023-12-01",
                      "duration": "15D",
                      "maxDailySpend": 10.00,
                      "status": "Upcoming"
                  }
              ]
          }
      },
      "warnings": [],
      "errors": []
  }
  ```
</CodeGroup>

### Update Line Item Budget Override

<EndpointBadge method="put">
  ```http theme={null}
  https://api.criteo.com/{version}/retail-media/line-items/{lineItemId}/line-item-budget-overrides
  ```
</EndpointBadge>

<Info>
  **Be careful with overlapping different overrides**

  Budget overrides cannot overlap. When scheduling a new override make sure it doesn't overlap with the duration of other overrides to avoid `400` validation errors.

  <Frame>
    <img src="https://mintcdn.com/criteo-e1682996/eCLtzx2Ch8FlxnxE/images/retail-media/v2025.01/docs/fdb6c02-image.png?fit=max&auto=format&n=eCLtzx2Ch8FlxnxE&q=85&s=d77bb7c9ee65e74d54ee3a4b06a99716" alt="" width="2417" height="1342" data-path="images/retail-media/v2025.01/docs/fdb6c02-image.png" />
  </Frame>
</Info>

**Sample Request**

<CodeGroup>
  ```bash Bash expandable theme={null}
  # Sample Request
  curl -L -X PUT 'https://api.criteo.com/{version}/retail-media/line-items/446397611671216128/line-item-budget-overrides' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <MY_ACCESS_TOKEN>' \
  -d '{
      "data": {
          "type": "<string>",
          "attributes": {
              "dailyLineItemBudgetOverrides": [
                  {
                      "duration": "5D",
                      "startDate": "2023-12-01",
                      "maxDailySpend": "5",
                      "status": "Upcoming"
                  },
                  {
                      "duration": "5D",
                      "startDate": "2023-12-06",
                      "maxDailySpend": "2",
                      "status": "Upcoming"
                  },
                  {
                      "duration": "2D",
                      "startDate": "2023-12-11",
                      "maxDailySpend": "5",
                      "status": "Upcoming"
                  }
              ],
              "monthlyLineItemBudgetOverrides": [
                  {
                      "duration": "3M",
                      "maxMonthlySpend": "12",
                      "startMonth": "2023-12",
                      "status": "Upcoming"
                  },
                  {
                      "duration": "3M",
                      "maxMonthlySpend": "12",
                      "startMonth": "2024-03",
                      "status": "Upcoming"
                  }
              ]
          }
      }
  }'
  ```
</CodeGroup>

**Sample Response**

<CodeGroup>
  ```json JSON expandable theme={null}
  {
      "data": {
          "type": "LineItemBudgetOverrides",
          "attributes": {
              "monthlyLineItemBudgetOverrides": [
                  {
                      "startMonth": "2023-12",
                      "duration": "6M",
                      "maxMonthlySpend": 12.00,
                      "status": "Upcoming"
                  }
              ],
              "dailyLineItemBudgetOverrides": [
                  {
                      "startDate": "2023-12-01",
                      "duration": "5D",
                      "maxDailySpend": 5.00,
                      "status": "Upcoming"
                  },
                  {
                      "duration": "5D",
                      "maxDailySpend": 2.00,
                      "status": "Upcoming"
                  },
                  {
                      "duration": "2D",
                      "maxDailySpend": 5.00,
                      "status": "Upcoming"
                  }
              ]
          }
      },
      "warnings": [],
      "errors": []
  }
  ```
</CodeGroup>

## **Responses**

| Response | Description                                                                                                                                                                                                                                                                           |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 🔵 `200` | Call executed with success                                                                                                                                                                                                                                                            |
| 🔵 `201` | Budget override was created with success                                                                                                                                                                                                                                              |
| 🔴 `400` | \* \*validation-errors\*\*:<ul><li>*Budget override dates must not overlap any existing budget overrides for this campaign / line item*</li><li>*Duration of daily budget override must end with D or d*</li><li>*Duration of monthly budget override must end with M or m*</li></ul> |