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

# Pause media buy

> Halt spend on a single media buy, without touching its campaign or sibling media buys

`POST /api/v2/buyer/media-buys/:mediaBuyId/pause`

Halts spend on exactly one media buy. The pause is sent to the seller's ad
server straight away, and the media buy transitions to `PAUSED` only after the
seller's storefront confirms that delivery has stopped.

Some sellers answer a pause with "accepted, still applying it" instead of
confirming at once. In that case the call returns `202 Accepted` with
`pauseRequestedAt` set: the media buy stays `ACTIVE`, and may keep
delivering, until the seller reports it paused. Apostra keeps checking, moves
the buy to `PAUSED` as soon as the seller confirms, and alerts its operations
team if the seller has not confirmed within two hours. The pause is not sent
again automatically.

<Note>
  A pause never waits for seller approval, even on a storefront that reviews
  every change manually. Pausing suspends delivery; it does not change the
  buy's budget, flight dates, or contract, so the seller is told it happened but
  is not asked to approve it. The same applies to guaranteed buys, and an
  earlier change to the buy that is still waiting for the seller does not hold
  the pause back.
</Note>

<Note>
  The same holds for a pause sent straight to a storefront's AdCP
  `update_media_buy`. One seller-specific limit applies on Meta; see
  [Pausing on each kind of storefront](/v2/buyer/campaigns/media-buys#pausing-on-each-kind-of-storefront).
</Note>

<Note>
  This does **not** cascade. It touches only the targeted media buy — never the
  parent campaign row and never any sibling media buy on the same campaign. To
  pause every media buy on a campaign at once, use
  [pause campaign](/v2/buyer/campaigns/tasks/pause-campaign) instead.
</Note>

<Note>
  To resume, use [reactivate media buy](/v2/buyer/campaigns/tasks/reactivate-media-buy) — pausing does not auto-resume, and there is no separate "unpause" verb.
</Note>

## Request

```bash theme={null}
curl -X POST https://api.apostra.com/api/v2/buyer/media-buys/mb_abc123/pause \
  -H "Authorization: Bearer $SCOPE3_API_KEY"
```

No request body.

## Parameters

| Field | Type | Required | Notes |
| - | - | - | - |
| `mediaBuyId` | string | Yes | Media buy ID (path parameter). Must currently be `ACTIVE`. |

## Response

```json theme={null}
{
  "mediaBuyId": "mb_abc123",
  "name": "Q2 2026 Tech Launch - Example Media",
  "previousStatus": "ACTIVE",
  "newStatus": "PAUSED",
  "success": true
}
```

* `mediaBuyId` — the media buy that was paused.
* `name` — the media buy's display name.
* `previousStatus` / `newStatus` — status before and after the call.
* `success` — `true` when the seller's storefront confirmed or accepted the
  pause. A pause the storefront refused or failed is returned as an error
  (see below), never as `success: false`.
* `pauseRequestedAt` — present only on a `202` response: when the seller
  accepted the pause it is still applying. `newStatus` is then `ACTIVE`.

### When the seller is still applying the pause

```json theme={null}
{
  "mediaBuyId": "mb_abc123",
  "name": "Q2 2026 Tech Launch - Example Media",
  "previousStatus": "ACTIVE",
  "newStatus": "ACTIVE",
  "success": true,
  "pauseRequestedAt": "2026-10-05T21:00:00.000Z"
}
```

Returned with HTTP `202`. Read the buy with `GET /media-buys/:mediaBuyId`
(see [Why isn't my buy live?](/v2/buyer/campaigns/media-buys#one-call-lookup)): `pauseRequestedAt`
stays set while the seller is applying the pause, and the buy's `status`
becomes `PAUSED` once the seller confirms. Pausing again before then is safe;
it asks the seller again and keeps the original `pauseRequestedAt`.

## Errors

| Code | HTTP status | When |
| - | - | - |
| `CONFLICT` | 409 | The media buy is not currently `ACTIVE` (error message includes the current status, e.g. `"is PAUSED, not ACTIVE"`). Nothing was sent to the seller. |
| `SERVICE_UNAVAILABLE` | 503 | The seller's storefront or ad server refused the pause, failed, or did not confirm it. The media buy stays `ACTIVE` and **delivery may be continuing**. The message carries the seller's reason when one was given, and Apostra's operations team is alerted. Retrying is safe; if it keeps failing, contact the seller to stop delivery directly. |
| `NOT_FOUND` | 404 | The media buy ID does not exist, or does not belong to the authenticated account. |

### Checking that delivery stopped

A `200` response with `newStatus: "PAUSED"` means the seller's storefront
confirmed the pause. A `202` response means the seller accepted it but has not
stopped delivery yet; treat the buy as still delivering until it reads
`PAUSED`. Any error response means Apostra could not confirm the pause, so
treat the buy as still delivering until a retry succeeds or the seller confirms
it out of band. The seller is notified when a buyer pause takes effect on their
ad server.

See [Errors](/v2/reference/errors) for the full error shape and recovery semantics.

## Related

<CardGroup cols={2}>
  <Card title="Reactivate media buy" href="/v2/buyer/campaigns/tasks/reactivate-media-buy" icon="circle-play">
    Resume this single PAUSED media buy back to ACTIVE
  </Card>

  <Card title="Pause campaign" href="/v2/buyer/campaigns/tasks/pause-campaign" icon="pause">
    Halt spend across every media buy and package on the campaign
  </Card>

  <Card title="Media buy" href="/v2/buyer/campaigns/media-buys" icon="receipt">
    The media buy object, status table, and cascade behavior
  </Card>

  <Card title="Get media buy status" href="/v2/buyer/campaigns/tasks/get-media-buy-status" icon="signal-stream">
    Poll live ADCP status
  </Card>
</CardGroup>


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