List plan suggestion sets

GET /api/v2/buyer/plan-suggestion-sets Lists the plan suggestion sets for your account, newest activity first. Filter on status=AWAITING_APPROVAL to see only the decisions outstanding. See plan suggestion sets for what a set is and why it is decided as a whole.

The list reports each set’s planMediaBuyCount — the number of media buys the optimizer declared for the run — but not its per-media-buy breakdown. That count is a declaration, not a membership count: a set still awaiting messages can declare four and have none yet. Read a single set when you need to see where the money goes.

Request

curl "https://api.interchange.io/api/v2/buyer/plan-suggestion-sets?status=AWAITING_APPROVAL&limit=20" \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

Parameters

Field	Type	Required	Notes
`status`	string	No	One of the set statuses. `AWAITING_APPROVAL` is the only actionable one.
`planId`	string	No	Plan id — digits only, no leading zero, up to 15 digits.
`campaignId`	integer	No	Restrict to one campaign.
`limit`	integer	No	1–100. Defaults to 20. Counts sets, which is all this response carries.
`offset`	integer	No	Defaults to 0.

Response

{
  "planSuggestionSets": [
    {
      "planSuggestionSetId": "77",
      "optimizerRunId": "8f14e45f-ceea-4c11-8e94-1c1a3c1e2f21",
      "planId": "555000000001",
      "planName": "Nike Q1 Brand Awareness Plan",
      "campaignId": "1042",
      "campaignName": "Nike Q1 Brand Awareness",
      "planRunSequence": "42",
      "planMediaBuyCount": 2,
      "budgetCurrency": "USD",
      "applyMode": "MANUAL",
      "status": "AWAITING_APPROVAL",
      "statusReason": null,
      "netAllocationDelta": "0",
      "notifiedAt": "2026-08-19T06:00:12.400Z",
      "decidedAt": null,
      "appliedAt": null,
      "applyAttemptCount": 0,
      "compensationAttemptCount": 0,
      "firstMessageAt": "2026-08-19T06:00:09.100Z",
      "lastMessageAt": "2026-08-19T06:00:11.800Z"
    }
  ],
  "hasMore": false
}

netAllocationDelta is in minor units of budgetCurrency — cents for USD, whole yen for JPY — and is "0" for any set eligible to apply, because the transfers inside it cancel out. It is null on a set that is not complete, since there is nothing balanced to report yet. Every allocation figure travels as a string, and that is not because the values are too large for a JSON number — most are comfortably inside the exact integer range. They are stored as int64, and the driver surfaces int64 as a decimal string so no value can ever be silently rounded on the way out. Keep them as strings or parse to a big-integer type; do not route them through a float.

Start building

Core Concepts

Buyer operations

Seller operations

Cross-Cutting Reference

Buyer API reference

Seller API reference

Release Notes

List plan suggestion sets

Request

Parameters

Response

​Request

​Parameters

​Response

Request

Parameters

Response