Skip to main content
POST /api/v2/buyer/discovery/{discoveryId}/products Adds products to the session selection. Each product must already have been surfaced by Discover products or Browse products — pass the productId, salesAgentId, groupId, and groupName from those results. Optionally pin a budget, pricing option, or bid. By default products merge into the existing selection; set replace: true to swap the whole set.

​
Request

curl -X POST https://api.interchange.io/api/v2/buyer/discovery/disc_01HZX3YQ7K9R6V3M2P1E0F8B2T/products \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "products": [
      {
        "productId": "prod_acme_ctv_sports",
        "salesAgentId": "agent_acme_media",
        "groupId": "ctx_disc_01HZX3-group-0",
        "groupName": "Acme Media Connected TV",
        "pricingOptionId": "po_fixed_30",
        "budget": 150000
      }
    ]
  }'

​
Parameters

FieldTypeRequiredNotes
productsarrayYesProducts to add (min 1)
products[].productIdstringYesProduct ID from the discovery results
products[].salesAgentIdstringYesSales agent the product came from
products[].groupIdstringYesGroup the product was discovered in
products[].groupNamestringYesName of that group
products[].pricingOptionIdstringNoPricing option ID from the product’s pricingOptions
products[].bidPricenumberNoBid for non-fixed options (isFixed: false); read from pricingOptions[].rate or floorPrice
products[].budgetnumberNoBudget allocation for this product
replacebooleanNoWhen true, replaces all existing products instead of merging

​
Response

{
  "discoveryId": "disc_01HZX3YQ7K9R6V3M2P1E0F8B2T",
  "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": 1,
  "budgetContext": { "sessionBudget": 250000, "allocatedBudget": 150000, "remainingBudget": 100000 }
}
Returns the full selection after the add, so you do not need a separate Get products call to confirm.

​
Errors

  • 400 VALIDATION_ERROR — empty products, missing a required selection field, or a productId not present in the session’s discovery results.
  • 404 NOT_FOUND — discoveryId does not exist or is not visible to the authenticated customer.
See Errors for the full error contract.

Discovery overview

Selection model and budget allocation

Get products

List the current selection

Remove products

Drop products from the selection

Apply proposal

Add a whole proposal at once