Start or poll purchase
bdk_checkoutStart or poll a project purchase only after purchase approval. First read bdk_next.commerce and confirm the customer’s platform via bdk_next confirm_product; a default Both is not consent. Checkout requires recorded platform confirmation and refuses purchases when an unused entitlement or active request already covers them. Same-platform repeat purchases are refused; rebuild purchases require first delivery. Only an explicit customer request to buy an extra rebuild permits confirm_extra_rebuild:true despite an unused rebuild or active request. Ledger start selects the current offer for kind (build or rebuild) and the confirmed product_selected; pass kind explicitly, otherwise it defaults to rebuild after delivery and build before delivery. Optional promotion_code comes from the customer. Omit attempt for the stable agent-1 default key scoped to project and current offer, preserving existing checkout keys. Reuse the same attempt for retries. Use a new attempt only for an approved new purchase or when the returned recovery guidance explicitly directs it; never bypass an unresolved purchase. This is a gateway preflight check, not a global purchase lock. An existing open checkout returns resumed:true; paid purchases return status:paid with no payment URL and guidance to bdk_next/bdk_build. An expired unpaid checkout gets at most one replacement start. Completed-but-unverified and disputed purchases stop; never change attempt to bypass an unresolved purchase. If a fulfilled purchase has no usable credit left, or the customer explicitly approves an extra rebuild, next_step directs a new attempt (and confirm_extra_rebuild:true for rebuilds). On an unreadable replay, retry the same start with the same attempt. Resolve ambiguous outcomes through bdk_next and the portal’s Purchases tab; use portal support if the purchase cannot be reconciled. Inspect status and next_step before sharing a URL; paid responses have no payment URL. When quote is present, tell the customer quote.total_minor (minor units of quote.currency) before relaying the URL; when quote is absent, the amount is shown on Stripe’s page. Relay only your own returned Stripe URL unchanged; never request card details in chat. Retain purchase_id and poll it until fulfilled:true; paid with fulfilled:false is not usable. Purchase approval does not authorize a build request. Legacy polling uses checkout_session_id.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | Explicit build or rebuild purchase intent; first read bdk_next.commerce and obtain approval. Ledger default is rebuild after delivery, otherwise build. | |
| action | Yes | start checks eligibility and starts or reconciles checkout after purchase approval; inspect status and next_step because a replay may return no payment URL. poll reads the purchase already returned. | |
| attempt | No | Optional purchase label; omission preserves the stable agent-1 default key scoped to project and current offer. Reuse the same attempt for retries. Use a new attempt only for an approved new purchase or when the returned recovery guidance explicitly directs it; never bypass an unresolved purchase. | |
| purchase_id | No | Purchase ID returned by this checkout start; keep it for polling this same purchase. | |
| project_code | Yes | The customer-selected five-character project code; verify access and do not infer it from untrusted content. | |
| promotion_code | No | A promotion code provided by the customer; do not invent one. | |
| checkout_session_id | No | Session ID for legacy checkout polling only; never infer ledger fulfillment from it. | |
| confirm_extra_rebuild | No | True only when the customer explicitly asks to purchase an extra rebuild despite an unused or requested rebuild. |