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

# Plan suggestion sets

> How optimizer suggestions that move budget between media buys are approved

When Scope3's optimizer works across a whole **plan** rather than one media buy at
a time, its recommendations stop being independent. Taking budget out of one
media buy is what funds putting budget into another, so the two halves are one
decision. A **plan suggestion set** is that decision: every media buy the
optimizer moved money between, grouped under the single run that computed them.

<Note>
  If you are not receiving sets yet, nothing is missing — see
  [Availability](#availability).
</Note>

## Why a set is approved as a whole

Each member of a set carries a `netAllocationDelta` — the amount that media buy
gains or gives up. Those are transfers, not standalone recommendations, and they
sum to exactly zero across the set.

That is why there is no way to approve one media buy's share on its own.
Approving a `+4000` minor units without its offsetting `-4000` would create
budget that the plan never freed; approving the `-4000` alone would strand it. And rescaling a
subset so it balances by itself produces an allocation the optimizer never
evaluated against your goals or your sellers' capacity. So the set is the unit:
you approve all of it, or none of it.

The per-media-buy breakdown is there so you can see what the transfer does —
[read a single set](/v2/buyer/campaigns/tasks/get-plan-suggestion-set) to get it.
It is not there so that parts of it can be actioned separately.

## The lifecycle of a set

<Steps>
  <Step title="Awaiting messages">
    The optimizer publishes one message per media buy it evaluated, and they
    arrive independently. Until all of them have, the set is incomplete and
    Interchange will not act on it — applying half a transfer would leave your
    plan's budget unbalanced. A set can sit here legitimately while the rest of
    the run arrives.
  </Step>

  <Step title="Awaiting approval">
    The set is complete and balanced, and it is yours to decide. You are notified
    when a set reaches this state.
  </Step>

  <Step title="Approved or rejected">
    Your decision applies to the whole set.
    [Approve](/v2/buyer/campaigns/tasks/approve-plan-suggestion-set) it, or
    [reject](/v2/buyer/campaigns/tasks/reject-plan-suggestion-set) it — rejection
    optionally carries a reason; approval takes no body.
  </Step>
</Steps>

If optimizations are set to apply automatically, a complete set goes straight to
approved without waiting for you. That setting is read from the campaign, falling
back to the advertiser's default when the campaign does not set one — so a set
can auto-approve on a campaign that appears to specify nothing. It is fixed when
the run is first seen, so changing it mid-run affects the next run, not one
already in flight.

### Statuses you may see

| Status              | Meaning                                                                                                                                                    |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AWAITING_MESSAGES` | Not every media buy in the run has reported yet. Nothing to decide.                                                                                        |
| `AWAITING_APPROVAL` | Complete and balanced. Waiting on your decision.                                                                                                           |
| `APPROVED`          | Accepted — by you, or automatically if the campaign applies optimizations without review.                                                                  |
| `REJECTED`          | Declined. Nothing moves.                                                                                                                                   |
| `SUPERSEDED`        | A newer, complete run for the same plan replaced this one. Decide the newer set instead.                                                                   |
| `EXPIRED`           | A media buy in the set changed after the optimizer read it, so the recommendation no longer describes your campaign. A later run will produce a fresh set. |
| `PARKED`            | Held back because the run did not satisfy its own consistency rules. Scope3 is alerted; you do not need to act.                                            |

`SUPERSEDED`, `EXPIRED` and `PARKED` are all terminal and require nothing from
you. Of the states above, only `AWAITING_APPROVAL` is actionable.

These are the states a set can reach today. The `status` filter accepts the full
enum, and further states will appear as automatic application of an approved set
ships — so treat an unrecognised status as "not actionable by me" rather than
assuming this list is closed.

## Finding sets that need you

[List plan suggestion sets](/v2/buyer/campaigns/tasks/list-plan-suggestion-sets)
and filter on `status=AWAITING_APPROVAL` to see just the decisions outstanding.
You can also filter by `planId` or `campaignId`.

The list gives you each set's `planMediaBuyCount` but not its per-media-buy
breakdown — a single plan can span many media buys, and a list is for finding the
set you care about. Fetch that one set to see where the money goes.

`planMediaBuyCount` is the number of media buys the optimizer **declared** for
the run, not the number reported so far. A set still in `AWAITING_MESSAGES` can
declare four and return an empty `mediaBuys` array, because membership is fixed
only once the set is complete.

## How a set relates to a suggestion

A plan suggestion set is made of ordinary optimization suggestions — one per
member media buy — and each still appears through
`GET /api/v2/buyer/optimization-suggestions` as usual. What changes is where the
decision lives: a suggestion that belongs to a set cannot be approved or rejected
on its own, and attempting it returns `409` naming the set to decide instead.

## Availability

Plan-scoped optimization is being rolled out. Until it is enabled for your
account these endpoints are live and correct but will return an empty list, and
you will not receive approval notifications for sets. Nothing about your existing
per-media-buy optimization suggestions changes in the meantime.