Create proposal

POST /api/v2/storefront/proposals Saves a discover-products response for a buyer (operator) and mints a shareable proposalCode. The server reads the cached snapshot for the named discovery session, freezes the chosen proposal as the offer, and assigns it to the operator. The buyer redeems the code on discover_products to receive the exact frozen products and proposals. The proposal is created in active status.

Request

curl -X POST https://api.interchange.io/api/v2/storefront/proposals \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operatorId": { "domain": "acme.com" },
    "label": "Acme Q3 RFP — CTV",
    "notes": "Offline RFP follow-up; honors the upfront rate.",
    "expiresAt": "2026-09-30T23:59:59Z",
    "discoveryId": "disc_a1b2c3",
    "proposalId": "proposal_abc123"
  }'

{
  "operatorId": "acme.com",
  "operatorRef": { "domain": "acme.com" },
  "label": "Acme Q3 RFP — CTV",
  "notes": "Offline RFP follow-up; honors the upfront rate.",
  "expiresAt": "2026-09-30T23:59:59Z",
  "discoveryId": "disc_a1b2c3",
  "proposalId": "proposal_abc123"
}

Parameters

Field	Type	Required	Notes
`operatorId`	string or object	Yes	Buyer identity for redemption. Prefer `{ "domain": "brand.example" }`; legacy strings are treated as domains, and `customer:<id>` is decoded as `{ "customerId": id }`.
`label`	string	Yes	Seller’s internal label for the proposal (1..255 chars)
`expiresAt`	string	Yes	When the code expires (ISO 8601). Must be no later than the underlying `proposal.expiresAt`
`discoveryId`	string	Yes	Discovery session ID from a recent `discover_products` call. Must be scoped to this seller and restricted to its storefront sales agents (1..255 chars)
`proposalId`	string	Yes	Which proposal from the discovery snapshot to freeze and associate with the code (1..255 chars)
`notes`	string	No	Free-form notes about the offline RFP (max 4000 chars)

Response

201 Created with the new proposal:

{
  "id": 318,
  "proposalCode": "PRP-XK4A29",
  "operatorId": "acme.com",
  "operatorRef": { "domain": "acme.com" },
  "label": "Acme Q3 RFP — CTV",
  "notes": "Offline RFP follow-up; honors the upfront rate.",
  "status": "active",
  "expiresAt": "2026-09-30T23:59:59Z",
  "proposalId": "proposal_abc123",
  "discoverySessionId": "disc_a1b2c3",
  "snapshot": { "products": [], "proposals": [] },
  "createdAt": "2026-06-07T15:00:00Z",
  "createdBy": "seller@acme-media.example.com",
  "firstViewedAt": null,
  "lastViewedAt": null,
  "redeemedAt": null,
  "redeemedInMediaBuyId": null
}

proposalCode is the short handle you hand to the buyer; they pass it to discover_products to redeem. id is the numeric row ID you pass to every sibling operation. snapshot holds the frozen products[] and proposals[] returned to the buyer on redemption — including each composed product’s ext.scope3_merchandise block (property, available delivery, and audience facts) when the underlying discovery response resolved one; see the story-first proposal for what that block states.

Errors

400 VALIDATION_ERROR — missing required field, expiresAt later than the underlying proposal.expiresAt, or a discoveryId not scoped to this seller’s storefront sales agents.

See Errors for the full error contract.

Proposal tasks

All proposal operations

Proposals overview

Lifecycle and concepts

Get proposal

Read back the saved snapshot

Revoke proposal

Withdraw a code before redemption

Start building

Core Concepts

Buyer operations

Seller operations

Cross-Cutting Reference

Buyer API reference

Seller API reference

Release Notes

Request

Parameters

Response

Errors

Proposal tasks

Proposals overview

Get proposal

Revoke proposal

​Request

​Parameters

​Response

​Errors

​Related

Proposal tasks

Proposals overview

Get proposal

Revoke proposal

Request

Parameters

Response

Errors

Related