Budget Overrides

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

Method	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

Attribute	Data Type	Description
`monthlyBudgetOverrides`	list<object>	Line item budget override monthly part, chronological order restrictedParameters:- `startMonth`

duration
maxMonthlySpend
status | | dailyLineItemBudgetOverrides | list<object> | Line item budget override daily part, chronological order restrictedParameters:- startDate
duration
maxDailySpend
status | | startMonth | string | Start month of monthly budget override.- *Note**: if null, the startMonth would be the following month of the last item in the override sequence.Accepted values: strings of date YYYY-MM Writeable? Y / Nullable? Y | | startDate | date | Start date of daily budget override- *Note**: if null, the startDate would be the following date of the last item in the override sequenceAccepted values: YYYY-MM-DD Writeable? Y / Nullable? Y | | duration | string | The number of months (for monthly Budget Override) or days (daily Budget Override) that the override is active, from startMonth or startDate, respectivelyAccepted values:- 1M, 2M, 3M… for monthly override (must end with M or m)
1D, 2D, 3D… for daily override (must end with D or d) Writeable? Y / Nullable? N | | maxMonthlySpend | decimal | Monthly budget override maximum monthly spend amountAccepted values: maxMonthlySpend ≥ 0.0 Writeable? Y / Nullable? N | | maxDailySpend | decimal | Daily budget override maximum daily spend amountAccepted values: maxDailySpend ≥ 0.0 Writeable? Y / Nullable? N | | status | enum | Monthly or daily budget override computed statusAccepted values: Expired, Active, Upcoming Writeable? N / Nullable? N |

Get Campaign Budget Override

Retrieves all existing budget overrides at campaign level: Sample Request

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

Sample Response

{
    "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": []
}

Update Campaign Budget Override

Sample Request

# 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"
        }
      ]
    }
  }
}'

Sample Response

{
    "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": []
}

Get Line Item Budget Override

Retrieves all existing budget overrides at line item level: Sample Request

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

Sample Response

{
    "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": []
}

Update Line Item Budget Override

Be careful with overlapping different overridesBudget 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.

Sample Request

# 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"
                }
            ]
        }
    }
}'

Sample Response

{
    "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": []
}

Responses

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

Introduction

Guides for Retail Media API

Endpoints

Budget Override Attributes

Get Campaign Budget Override

Update Campaign Budget Override

Get Line Item Budget Override

Update Line Item Budget Override

Responses

​Endpoints

​Budget Override Attributes

​Get Campaign Budget Override

​Update Campaign Budget Override

​Get Line Item Budget Override

​Update Line Item Budget Override

​Responses

Endpoints

Budget Override Attributes

Get Campaign Budget Override

Update Campaign Budget Override

Get Line Item Budget Override

Update Line Item Budget Override

Responses