Create proposal

POST /api/v2/storefront/proposals Saves a discover-products response against a buyer (operator) binding and mints a shareable proposalCode. The server reads the cached snapshot for the named discovery session, freezes the chosen proposal as the offer, and binds 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 binding for redemption. Prefer `{ "domain": "brand.example" }`; legacy strings are treated as domain bindings, 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 bind to 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.

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

Getting Started

Operating Your Storefront

Inventory Sources

Real-Time Targeting (TMP)

Approvals & Reviews

Buyer Onboarding

Demand & Signals

Proposals & Agents

Buyer Routing

Analytics & Activity

Billing

Account

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