> ## 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. They are separate, and Apostra never turns one
into the other: it never adds a daily cap because you asked for `even` pacing.

This matters on products that cannot pace. A Google Ad Manager product sold as
a Price Priority line item delivers `asap`, as fast as it can win, whatever
pacing it is asked for, and `even` on such a product stays `asap`. To limit how
much of its budget such a line item spends each day, set
`products[].daily_budget_cap` on a seller that declares `package` caps.


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