Add products

POST /api/v2/buyer/discovery/{discoveryId}/products Adds products to the session selection. Pass the productId from your Discover products or Browse products results. When a result includes inventorySourceId, preserve it in the selection so identical product IDs from different inventory sources remain unambiguous. salesAgentId, groupId, and groupName are optional and resolved server-side from those results, so pass them only to disambiguate a product that appears in more than one group. Optionally pin a budget, pricing option, bid, or per-line-item targeting. By default products merge into the existing selection; set replace: true to swap the whole set. When you pass pricingOptionId, Apostra validates it against the exact pricing in the session’s current discovery result and carries that option into campaign staging. A separate catalog refresh cannot invalidate an option that result just returned. Re-run discovery when the option is no longer present in the current result or its quoted price has expired. Older sessions whose results predate pricing evidence recording use current catalog validation and may also require a new discovery run. To select the same product more than once, omit selectionId for its single base selection and give each repeat a distinct selectionId. Each selection becomes an independent media-buy line item. Re-sending an existing selectionId updates that instance instead of adding another copy.

Request

curl -X POST https://api.apostra.com/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
      }
    ]
  }'

{
  "products": [
    {
      "productId": "prod_example_olv_open",
      "salesAgentId": "agent_example_media",
      "groupId": "ctx_disc_01HZX3-group-1",
      "groupName": "Example Media CTV",
      "bidPrice": 12.5,
      "budget": 50000
    }
  ]
}

{
  "products": [
    {
      "productId": "prod_retailer_sponsored_products",
      "salesAgentId": "agent_retailer_media",
      "groupId": "ctx_disc_01HZX3-group-2",
      "groupName": "Retailer Sponsored Products",
      "pricingOptionId": "po_cpc_auction",
      "bidPrice": 1.25,
      "budget": 10000,
      "targetingOverlay": {
        "product_codes": ["sku-coffee-250g", "sku-coffee-1kg"],
        "keyword_targets": [
          { "keyword": "ground coffee", "match_type": "exact" },
          { "keyword": "arabica coffee", "match_type": "phrase" }
        ],
        "negative_keywords": [
          { "keyword": "instant coffee", "match_type": "exact" }
        ]
      }
    }
  ]
}

{
  "products": [
    {
      "productId": "prod_acme_ctv_sports",
      "pricingOptionId": "po_fixed_30",
      "budget": 90000,
      "targetingOverlay": { "geo_countries": ["US"] }
    },
    {
      "productId": "prod_acme_ctv_sports",
      "selectionId": "prod_acme_ctv_sports::uk-flight",
      "pricingOptionId": "po_fixed_30",
      "budget": 60000,
      "targetingOverlay": { "geo_countries": ["GB"] }
    }
  ]
}

Parameters

Field	Type	Required	Notes
`products`	array	Yes	Products to add (min 1)
`products[].productId`	string	Yes	Product ID from the discovery results
`products[].inventorySourceId`	string	When returned	Typed inventory-source ID from the discovery result. Preserve it when present to distinguish identical product IDs from different sources.
`products[].selectionId`	string	No	Per-instance line-item identity. Omit for the product’s base selection. Use a distinct value to add the same product again; re-send the same value to update that instance.
`products[].salesAgentId`	string	No	Sales agent the product came from. Resolved server-side from your discovery results when omitted; pass to disambiguate.
`products[].groupId`	string	No	Group the product was discovered in. Resolved server-side from your discovery results when omitted.
`products[].groupName`	string	No	Name of that group. Resolved server-side from your discovery results when omitted.
`products[].pricingOptionId`	string	No	Pricing option ID from the product’s `pricingOptions`
`products[].bidPrice`	number	No	Bid for non-fixed options (`isFixed: false`); read from `pricingOptions[].rate` or `floorPrice`
`products[].budget`	number	No	Budget allocation for this product
`products[].targetingOverlay`	object	No	Per-line-item AdCP targeting. For sponsored products, use source-supported fields such as promoted product codes and keyword targets.
`products[].pageId`	string	No	Meta Facebook Page ID. Required for Meta products when the connected ad account has more than one authorized Page — pass one of the page IDs listed in the error message. Omit when the account has exactly one authorized page (the server selects it automatically). Fixed at ad creation; cannot change after execution.
`products[].pixelId`	string	No	Meta Pixel / Dataset ID for conversion tracking. Required for Meta Sales (OUTCOME_SALES) products — pass the pixel ID listed in the error message. There is no auto-select: every Meta Sales buy must explicitly specify a pixel. Fixed at ad creation; cannot change after execution.
`products[].instagramActorId`	string	No	Meta Instagram account ID. Required for Instagram Direct destinations (Instagram Direct Conversations, Instagram-based Lead Generation) when the connected ad account has more than one authorized Instagram account. Omit when the account has exactly one (the server selects it automatically). Fixed at ad creation; cannot change after execution.
`products[].welcomeMessageFlowId`	string	No	Meta welcome message flow ID. Required for lead-to-message destinations (Messenger, Instagram Direct, and WhatsApp Lead Generation) — pass one of the welcome-message-flow candidates returned by account resource readiness in this response. Candidates only appear on a catalog-style `discover_products` call with no `brief` (a `buying_mode: "wholesale"` request that still includes a `brief` does not surface them). There is no auto-select, even with a single candidate. Fixed at ad creation; cannot change after execution.
`replace`	boolean	No	When `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. Repeat instances return their selectionId; the base instance omits it. Keep that value when updating or removing one repeat. Reconciliation preserves repeat instances as distinct line items, so their budget and targeting do not collapse into the base selection. If two or more submitted selections share the same identity — no selectionId, or the same selectionId — they merge into a single package instead of staying separate. The response then includes a warnings array (list of strings) naming each collapsed product. Treat that warning as a sign the request needs distinct selectionId values on the repeats, not as a successful add of multiple line items. Do not resend every collapsed selection with a new selectionId. The merge is additive by instance identity, and a brand-new selectionId never matches the surviving base instance, so resending all of them adds that many more entries on top of the one already stored — three collapsed selections resent with three new selectionIds produces four line items, not three. Instead, call Get products (or read the products array in this response) to see which configuration survived as the base instance — it holds whichever collapsed selection was submitted last — then resend only the configurations that did not survive, each with its own new selectionId.

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

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

Start building

Core Concepts

Buyer operations

Seller operations

Cross-Cutting Reference

Buyer API reference

Seller API reference

Release Notes

Request

Parameters

Response

Errors

Discovery overview

Get products

Remove products

Apply proposal

​Request

​Parameters

​Response

​Errors

​Related

Discovery overview

Get products

Remove products

Apply proposal

Request

Parameters

Response

Errors

Related