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

# Cap a buy's daily spend

> What a daily budget cap is, how to set one on a media buy or a line item, which sellers enforce it, and how it differs from pacing.

A daily budget cap is a hard ceiling on what a buy, or one line item in it,
spends in one day. It is AdCP's `daily_budget_cap`: the seller stops delivery
for the rest of the day once the cap is reached, and starts again the next day.
A cap never spends money on its own. It only limits what the buy's budget can
spend in a day.

You set it when you create a media buy with `save_media_buy`, from
`sellerAccountId` and `products`.

| Field | Where | What it caps |
| - | - | - |
| `daily_budget_cap` | On the media buy | Everything the buy spends in a day, across all its line items. |
| `products[].daily_budget_cap` | On one line item | What that line item spends in a day. |
| `budget_cap_timezone` | On the media buy | The IANA timezone, such as `America/New_York`, whose midnight starts each cap's day. |

Both caps are numbers in the buy's currency, gross of fees, like its budgets.
You can set either or both. A line item's cap is its own ceiling: it does not
take a share of the buy's cap, and the line items' caps need not add up to it.

```json theme={null}
{
  "campaignId": "CAMPAIGN_ID",
  "sellerAccountId": 2192,
  "products": [
    {
      "productId": "QUALIFIED_PRODUCT_ID",
      "budget": 3000,
      "daily_budget_cap": 100
    }
  ],
  "idempotencyKey": "PRODUCT_QUERY_ID"
}
```

## The rules

* A buy's cap is at most its total budget, and a line item's cap is at most its
  own budget. A larger cap is refused before anything is staged.
* A line item's budget is the one it is staged with. If you leave it out, the
  line item gets a share of the campaign's budget, and a budget you state can
  be scaled down to fit what the campaign has left. A cap above the staged
  budget is refused, and nothing is staged.
* With `budgetAllocation.mode` `seller_optimized` the seller splits one shared
  budget across the buy, so no line item has a budget of its own to cap. Such a
  buy takes only the buy's `daily_budget_cap`.
* A campaign's `budget.dailyCap` bounds the sum of its buys' own caps. It does
  not count line item caps. See
  [Buyer workflows](https://docs.apostra.com/v2/setup/v3/buyer-workflows.md#cap-a-media-buys-daily-spend).
* The caps are saved with the draft and go to the seller when you launch, net of
  the buy's fees, like its budgets.
* `budget_cap_timezone` needs a cap on the buy or on a line item. Omit it to use
  the seller's default day.
* You set caps when you create the buy. Setting or changing a cap on an existing
  buy is not supported yet: `save_media_buy` with `mediaBuyId` refuses
  `daily_budget_cap` and `products[].daily_budget_cap` as not implemented.
* `get(kind: "media_buy")` shows the buy's `daily_budget_cap` and
  `budget_cap_timezone`, and with `include: ["products"]` each line item's
  `daily_budget_cap`.

## Which sellers enforce a cap

A seller enforces a cap only when it says so in its AdCP
`get_adcp_capabilities`, under `media_buy.budget_capping`:

* `supported_scopes` lists where it enforces caps: `media_buy` for a cap on
  the whole buy, `package` for a cap on one line item.
* `timezone_basis` and `fixed_timezone` say whose day the caps run on: the
  account's timezone, or one fixed timezone, such as an ad server's network
  timezone.
* `buyer_timezone_override` says whether it takes your `budget_cap_timezone`.

Apostra checks the seller's declaration when you create the buy. A cap at a
scope the seller does not declare is refused with `UNSUPPORTED_FEATURE`, naming
the field, before anything is staged or sent. Apostra never accepts a cap and
then drops it, so a buy you launch with a cap carries the cap at the seller or
does not launch.

A seller can change its declaration after you create the buy, so Apostra
checks it again when you launch. If the seller no longer enforces a cap the buy
carries, or no longer takes its `budget_cap_timezone`, the launch is refused
with `UNSUPPORTED_FEATURE` before anything is sent, and the buy fails. Caps
cannot be changed on an existing buy yet, so create the buy again without that
cap.

When a seller is backed by several sources, every one of them must declare the
scope, since any of them may carry the buy. A seller connected through a
platform adapter takes a cap on the whole buy only when that adapter enforces a
hard daily cap, which none does today, and never takes a line item cap.

### When the seller sets the day itself

Some sellers run every cap on their own day and do not take
`budget_cap_timezone` (`buyer_timezone_override` is absent or `false`).

* If the seller runs its caps in one fixed timezone, you can omit
  `budget_cap_timezone` or send that same timezone. Any other timezone is
  refused with `UNSUPPORTED_FEATURE`, and the message names the seller's
  timezone. The cap resets at midnight in that timezone.
* If the seller runs its caps on the account's timezone, any
  `budget_cap_timezone` is refused. Omit it; the cap resets at midnight in the
  account's timezone.

Apostra keeps the timezone you sent on the buy, so your reads show it, but does
not send it to a seller that sets the day itself.

## A daily cap is not pacing

Pacing (`asap`, `even`, `front_loaded`) is how a seller spreads delivery over a
flight. A daily cap is a ceiling you set. They are separate, and Apostra never
turns one into the other: it never adds a daily cap because you asked for `even`
pacing, and it never paces a buy because you set a cap.

A seller can still use a daily limit of its own to deliver the pacing you ask
for. A Google Ad Manager product sold through Apostra's managed sales agent as a
Price Priority line item delivers as fast as it can win, whatever pacing it
stores. On such a product:

* **`even`** gets a daily goal in the unit the line is priced in: impressions for
  a CPM line, clicks for a CPC line. The goal spreads what the package's budget
  buys evenly over the days of its flight. Each day the seller's agent re-sizes it from
  the budget left over the days left, so a day that delivers less leaves more for
  the days after, and the daily goals never add up to more than the package's
  budget. Within each day the line item still delivers as fast as it wins.
* **`asap`** runs as fast as it wins, held only to the package's total budget.
* **`front_loaded`** is booked as `even`, and the buy reports it as `even`.

These Google Ad Manager sellers don't offer `daily_budget_cap`. They declare no
`budget_capping`, so a buy that sets a daily cap on them is refused with
`UNSUPPORTED_FEATURE`. To spread such a package's budget across its flight, ask
for `even` pacing.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.