Skip to main content
POST /api/v2/storefront/storefronts/{storefrontId}/demand-signals/{signalId}/respond Records a seller action against a demand signal routed to the caller’s storefront. The call is transactional: it writes the response, advances the per-target dispatch status (ACKNOWLEDGED for QUOTE/CLARIFY/BOOK, DECLINED for DECLINE), and re-evaluates the parent signal’s status. BOOK is terminal — once a signal is BOOKED it cannot move backward.

​
Request

curl -X POST https://api.interchange.io/api/v2/storefront/storefronts/4471/demand-signals/8821/respond \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "QUOTE",
    "payload": {
      "proposedCpm": 26.5,
      "currency": "USD",
      "products": [
        { "productId": "prod_ctv_primetime", "name": "CTV Primetime", "estimatedImpressions": 4200000 }
      ],
      "notes": "Can hold inventory through end of July."
    }
  }'

​
Parameters

FieldTypeRequiredNotes
storefrontIdintegerYesStorefront the caller owns (path)
signalIdintegerYesDemand signal identifier (path)
kindenumYesQUOTE, CLARIFY, DECLINE, or BOOK. Determines the payload shape
payloadobjectYesShape depends on kind (see below)
payload by kind:
  • QUOTE — proposedCpm (number, required, > 0), currency (3-letter, required), products[] (each productId required; optional name, estimatedImpressions), notes (optional, max 4000).
  • CLARIFY — question (required, max 4000), gaps[] (optional list of strings).
  • DECLINE — reason (required, max 4000).
  • BOOK — dealId (required), notes (optional, max 4000).

​
Response

{
  "id": "dsr_91c2",
  "demandSignalId": "ds_8f3a",
  "demandSignalTargetId": "tgt_22a",
  "sellerCustomerId": 4471,
  "storefrontId": "4471",
  "kind": "QUOTE",
  "payload": {
    "proposedCpm": 26.5,
    "currency": "USD",
    "products": [
      { "productId": "prod_ctv_primetime", "name": "CTV Primetime", "estimatedImpressions": 4200000 }
    ],
    "notes": "Can hold inventory through end of July."
  },
  "matchScore": 72,
  "actorUserId": 5503,
  "createdAt": "2026-06-06T15:20:00Z",
  "proposalCode": "PRP-XK4A29"
}
On a QUOTE the response carries a proposalCode the buyer’s agent can redeem via discover_products. proposalCode is null on DECLINE, or when operator resolution failed at quote time.

​
Errors

  • 400 VALIDATION_ERROR — payload does not match kind, missing required payload field, or proposedCpm ≤ 0.
  • 403 FORBIDDEN — the demand-supply-signals feature is not enabled, or the caller does not own the storefront.
  • 404 NOT_FOUND — the signal is not routed to this storefront.
See Errors for the full error contract.

Demand signal tasks

All demand-signal operations

Test-fit demand signal

Preview the match before responding

Get demand signal

One signal with its target row

List demand signals

Filterable, paginated list