---
title: "Start or resume a storefront checkout intent"
method: POST
path: "/v3/stores/{store_id}/public/checkout-intents"
tags: ["Storefront"]
---

# Start or resume a storefront checkout intent

`POST /v3/stores/{store_id}/public/checkout-intents`

## Request

- Base URL: `https://api.scalev.com`
- URL: `https://api.scalev.com/v3/stores/{store_id}/public/checkout-intents`
- Auth: none required

The path store unique ID and Storefront API key define the capture scope. Use a stable form_widget_id chosen by your storefront. Requires a reCAPTCHA token for action checkout_intent_start. Repeating client_session_id resumes the unfinished attempt without replacing saved snapshots; PATCH with last_sequence + 1 to save new input. A completed session returns 409; create a new client_session_id after checkout succeeds. A valid optional cip_ prefill token resumes its matching unfinished attempt; invalid or mismatched prefill tokens fall back to the client session. Capture failures must not block checkout.

## Request body

- StorefrontCheckoutIntentStartRequest
  - `recaptcha_token` string, required: reCAPTCHA token for action checkout_intent_start.
  - `client_session_id` string, uuid, required: Browser-persistent random UUID scoped to the page or storefront checkout; not a guest-cart token.
  - `checkout_intent_prefill_token` string: Optional cip_ recovery capability. Invalid or mismatched tokens fall back to client_session_id.
  - `form_widget_id` string, required: Stable identifier chosen by the storefront, for example storefront-checkout.
  - `fields` CheckoutIntentFields
    - `selected_order_bump_keys` string[]: Optional Builder offer selection metadata for recovery. Items still include the selected offer quantities. An empty array means no offers were selected. These keys do not authorize products or determine prices.
    - `customer_name` string, nullable
    - `customer_email` string, nullable
    - `customer_phone` string, nullable
    - `shipping_address` string, nullable
    - `shipping_province` string, nullable
    - `shipping_city` string, nullable
    - `shipping_subdistrict` string, nullable
    - `shipping_postal_code` string, nullable
    - `payment_method` string, nullable
    - `sub_payment_method` string, nullable
    - `notes` string, nullable
    - `discount_code_code` string, nullable
    - `shipping_location_id` integer, nullable
    - `custom_fields` object[]
      - `key` string, required
      - `label` string, required
      - `value` union
        - string, nullable
        - number
        - boolean
  - `items` CheckoutIntentItem[]
    - union
      - object
        - `type` 'variant', required
        - `variant_id` integer, required
        - `quantity` integer, required
      - object
        - `type` 'bundle_price_option', required
        - `bundle_price_option_id` integer, required
        - `quantity` integer, required
  - `attribution` CheckoutIntentAttribution
    - `ad_source` string, nullable
    - `utm_source` string, nullable
    - `utm_medium` string, nullable
    - `utm_campaign` string, nullable
    - `utm_content` string, nullable
    - `utm_term` string, nullable
    - `affiliate_code` string, nullable
    - `fbc` string, nullable
    - `fbp` string, nullable
    - `ttclid` string, nullable
    - `ttp` string, nullable
    - `gclid` string, nullable
    - `gbraid` string, nullable
    - `wbraid` string, nullable
    - `kwai_clickid` string, nullable
  - `source_url` string, uri, nullable: Current checkout URL. Sensitive query parameters and fragments are stripped. Recovery links are only issued for trusted source origins.
  - `cart_id` integer, nullable

## Response `201`

New or resumed checkout intent and write capability.

- CheckoutIntentCapture
  - `id` string, uuid, required
  - `form_widget_id` string, required
  - `checkout_intent_token` string, required: Write capability valid for 24 hours. Start/resume refreshes the window for an unfinished intent. Never include it in URLs or analytics.
  - `status` 'active' | 'abandoned' | 'completed', required
  - `last_sequence` integer, required
  - `started_at` string, date-time, required
  - `last_activity_at` string, date-time, required
  - `expires_at` string, date-time, required

## Other responses

- `400`: Malformed request.
- `403`: Checkout intent is not included in the active business subscription, or authorization failed.
- `404`: Source API key is missing or invalid, source was not found, or checkout intent does not belong to this source.
- `409`: The checkout intent is completed.
- `422`: Invalid capture fields, item references, sequence, form widget, or reCAPTCHA assessment.
- `429`: Too Many Requests. Storefront public requests using `X-Scalev-Storefront-Api-Key` or `X-Scalev-Guest-Token` are rate-limited as direct client/browser requests. Machine-authenticated business requests are rate-limited per API key or OAuth installation. Rate-limit responses may be plain text instead of the normal JSON error shape.

## Changes

- **2026-11-03** `6b9152f04622`: 2 info
  - added the new optional request property `attribution/gbraid`
  - added the new optional request property `attribution/wbraid`
- **2026-10-02** `a14339bcc086`: 1 info
  - added the new optional request property `fields/selected_order_bump_keys`
- **2026-09-16** `40f39d0fda73`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/scalev/apis/nexus-commerce-api/changes/v3/stores/:store_id/public/checkout-intents/post.md)

---

[API](https://skmtc.dev/scalev/apis/nexus-commerce-api.md) - [All operations](https://skmtc.dev/scalev/apis/nexus-commerce-api/llms.txt) - [OpenAPI document](https://skmtc.dev/scalev/apis/nexus-commerce-api/revisions/6b9152f04622?raw)