GuidesAPI ReferenceChangelog
GuidesAPI ReferenceChangelogLog In
Guides

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

VerbEndpointDescription
GETcampaigns/{campaignId}/campaign-budget-overridesRetrieves all existing budget overrides at the campaign level.
PUTcampaigns/{campaignId}/campaign-budget-overridesReplaces all existing campaign budget override settings. Use this endpoint can be used to add/remove or update existing budget overrides.
GETline-items/{lineItemId}/line-item-budget-overridesRetrieves all existing budget overrides at the line-item level.
PUT/line-items/{lineItemId}/line-item-budget-overrideReplaces all existing line-item budget override settings. Use this endpoint to add/remove or update existing budget overrides.

 

Budget Override Attributes

dailyLineItemBudgetOverrides

Data Type: object array

Description: Line item budget override monthly part, chronological order restricted.


dailyLineItemBudgetOverrides

Data Type: object array

Description: Line item budget override daily part, chronological order restricted.


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.


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.


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

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


maxMonthlySpend

Data Type: number (double)

Description: Monthly budget override maximum monthly spend amount.


maxDailySpend

Data Type: number (double)

Description: Daily budget override maximum daily spend amount.


status

Data Type: string

Description: Monthly or daily budget override computed status.


Campaigns

Get Campaign Budget Override

https://api.criteo.com/{version}/retail-media/campaigns/{campaignId}/campaign-budget-overrides

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

https://api.criteo.com/{version}/retail-media/campaigns/{campaignId}/campaign-budget-overrides

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

Line-items

Get Line Item Budget Override

Retrieves all existing budget overrides

https://api.criteo.com/{version}/retail-media/line-items/{lineItemId}/line-item-budget-overrides

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

https://api.criteo.com/{version}/retail-media/line-items/{lineItemId}/line-item-budget-overrides

🗯️

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.

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

ResponseDescription
🔵 200Call executed with success
🔵 201Budget override was created with success
🔴 400validation-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