POST /api/v1/funnels dispatches through operation. start requires a backend key with sessions:create and funnels:run; run operations use this run’s gg_fr_ credential. Independent native_receipt recovery requires the host backend key (billing:write and funnels:run) plus the current gg_ct_ customer session, without a run credential. Authentication additionally supplies the signed-in user’s gg_ct_ credential.
| operation | Input |
|---|---|
| decide | funnelId, requestId, customerId, attributes; backend API key |
| read_decision | decisionId; backend API key |
| feature_config | funnelId; backend API key |
| report_used | eventId, decisionId, occurredAt, reference?; backend API key |
| renew_run | runId, customerId; backend API key |
| signal | runId, nodeId, eventName, eventId, data; backend API key; sessions:create + funnels:run |
| read_results | runId; backend API key; sessions:create + funnels:run |
| start | source: funnel/id | paywall/id | trigger/key; requestId; customerToken (customer or guest session); locale?, commerce?, parameters? |
| get | customerToken?, data? |
| resume | original requestId; customerToken? |
| answers | requestId, nodeId, revision, answers |
| advance | requestId, nodeId, revision, output, answers |
| execute | requestId, nodeId, revision, intent: begin | confirm | cancel | fail; productVersionId?; nativeEvidence? |
| link | requestId, nodeId, revision, customerToken |
| back / shown / close | requestId, nodeId, revision |
| acknowledge | requestId, nodeId, revision, receiptId |
| native_receipt | requestId, customerToken, orderId, receiptId, nativeEvidence: proof | null; backend API key |
Operations and input
decide
- Input
- funnelId, requestId, customerId, attributes; backend API key
read_decision
- Input
- decisionId; backend API key
feature_config
- Input
- funnelId; backend API key
report_used
- Input
- eventId, decisionId, occurredAt, reference?; backend API key
renew_run
- Input
- runId, customerId; backend API key
signal
- Input
- runId, nodeId, eventName, eventId, data; backend API key; sessions:create + funnels:run
read_results
- Input
- runId; backend API key; sessions:create + funnels:run
start
- Input
- source: funnel/id | paywall/id | trigger/key; requestId; customerToken (customer or guest session); locale?, commerce?, parameters?
get
- Input
- customerToken?, data?
resume
- Input
- original requestId; customerToken?
answers
- Input
- requestId, nodeId, revision, answers
advance
- Input
- requestId, nodeId, revision, output, answers
execute
- Input
- requestId, nodeId, revision, intent: begin | confirm | cancel | fail; productVersionId?; nativeEvidence?
link
- Input
- requestId, nodeId, revision, customerToken
back / shown / close
- Input
- requestId, nodeId, revision
acknowledge
- Input
- requestId, nodeId, revision, receiptId
native_receipt
- Input
- requestId, customerToken, orderId, receiptId, nativeEvidence: proof | null; backend API key
Interactive responses contain scope and run. Starts also return runToken. run pins the Funnel version, node, revision, private customer data and instruction, with separate runExpiresAt and credentialExpiresAt. Browsers cannot select a customer ID, arbitrary next node or successful payment outcome. JSON queries return a decisionId and committed decision.value, state and validUntil; pending queries return 202.
- createFunnelRunController: get, submit, retry, resume, identify, link, subscribe and reset. Timeouts retain pendingCommand; retry replays its original requestId.
- showFunnelRun supports each screen’s modal, panel, fullscreen and embedded presentation. Host callbacks provide authentication, checkout navigation and account links.
- Viewing, refresh, filtering, paging and preview execute no business actions. Coupon claims, billing and cancellation run through their authored nodes and original receipts.
- createFunnelDecisionClient accepts verified customerId and complete attributes JSON. value is arbitrary business JSON; an allocationScopeId retains its first result, including null, zero and zero-offer objects. state is active, expired or inactive. features().init/refresh loads rules for synchronous evaluation. reportUsed records caller-reported usage only.
- renewFunnelRun(options, { runId, customerId }) is backend-only. It rotates the browser credential for the same identified customer's run and returns a new runToken and credentialExpiresAt; it does not start a run or extend runExpiresAt.
- JSON decision queries require sessions:create and funnels:run. submit uses Prefer: respond-async and returns current status without waiting; pending is HTTP 202. decide waits up to 30 seconds. DECISION_ACCEPTANCE_UNKNOWN means initial acceptance is uncertain: retry the original requestId and complete input. DECISION_PENDING retains decisionId: read that decision without cancelling background execution.