Skip to main content
POST /api/v2/buyer/discovery/{discoveryId}/apply-proposal Applies a seller proposal returned by Discover products, auto-adding its products with the proposal’s recommended budget allocations. Requires discover-products to have run first so the proposal’s products are in the session cache. Defaults the distributed budget to proposal.totalBudgetGuidance.recommended; set replace: true to clear the existing selection before applying.

​
Request

curl -X POST https://api.interchange.io/api/v2/buyer/discovery/disc_01HZX3YQ7K9R6V3M2P1E0F8B2T/apply-proposal \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "proposalId": "proposal_acme_q3_sports",
    "totalBudget": 250000,
    "replace": true
  }'

​
Parameters

FieldTypeRequiredNotes
discoveryIdstringYesPath param — session to apply into
proposalIdstringYesProposal ID from the discover-products response
totalBudgetnumberNoBudget to distribute across products. Defaults to totalBudgetGuidance.recommended
replacebooleanNoWhen true, clears existing selected products before applying

​
Response

{
  "discoveryId": "disc_01HZX3YQ7K9R6V3M2P1E0F8B2T",
  "proposal": {
    "proposalId": "proposal_acme_q3_sports",
    "name": "Q3 Sports - premium CTV mix",
    "salesAgentName": "Acme Media Ad Sales"
  },
  "totalBudgetUsed": 250000,
  "productsApplied": 2,
  "productsSkipped": [],
  "products": [
    {
      "productId": "prod_acme_ctv_sports",
      "salesAgentId": "agent_acme_media",
      "bidPrice": 32.5,
      "budget": 150000,
      "groupId": "ctx_disc_01HZX3-group-0",
      "groupName": "Acme Media Connected TV",
      "selectedAt": "2026-06-07T15:04:00Z"
    }
  ],
  "totalProducts": 2,
  "budgetContext": { "sessionBudget": 250000, "allocatedBudget": 250000, "remainingBudget": 0 }
}
productsSkipped is non-empty when a proposal references a product that has aged out of the cached discovery results. Re-run discover to refresh the session, then re-apply.

​
Errors

  • 400 VALIDATION_ERROR — missing proposalId, non-positive totalBudget, or discover-products was never run for this session.
  • 404 NOT_FOUND — discoveryId or proposalId not found for the authenticated customer.
See Errors for the full error contract.

Discovery overview

Proposals and refinement

Discover products

Surface proposals to apply

Get products

Inspect the resulting selection

Add products

Add products one at a time instead