The Constructor + Stripe integration lets shoppers move from product discovery to checkout within an agentic experience, such as the AI Shopping Agent (ASA) or Product Insights Agent (PIA).

Constructor’s Checkout UI library provides everything you need to integrate Stripe's Embedded Checkout form within the above agentic experiences. This article covers the backend setup and Stripe Checkout Session configuration patterns commonly required with this integration.

Scope and responsibilities

Constructor provides:

Client-side Checkout UI library components and APIs used to render and orchestrate the checkout experience

You are responsible for:

Creating and managing the shopper’s cart and pricing logic
Creating and (optionally) updating Stripe Checkout Sessions
Tax configuration, tax registrations, and product tax code mapping (when applicable)
Shipping carrier logic and rate calculation (when applicable)

Payment security and data handling

Stripe hosts the embedded checkout UI and handles payment details.

Constructor does not receive or store shopper payment card details.
Your backend creates Stripe Checkout Sessions using your Stripe secret key.
The UI library only receives the Stripe clientSecret plus your Stripe publishable key.

Requirements

Stripe

Stripe account with Embedded Checkout enabled
Stripe server SDK v18+
Stripe must enable ui_mode: 'form' (embedded form) on your account if you plan to use form mode

Library

Minimum supported versions noted below:

Node.js >= 18
React >= 16.12.0
React DOM >= 16.12.0
@stripe/stripe-js >= 9.3.1
@stripe/react-stripe-js >= 6.6.0
@constructor-io/constructorio-ui-components >= 1.4.0

Your application

You will need:

A server endpoint that creates Stripe Checkout Sessions and returns { clientSecret, publishableKey }
A place in your agent experience to mount a multi-step checkout experience (modal, routed pages, or single-page)
Access to current cart contents and currency in your app (used to build line_items)

Recommended:

A stable cart identifier (to help prevent duplicate checkout sessions when requests are retried)

Agent and checkout UI libraries

Constructor's agent UI libraries provide the “agent surface” where the shopper interaction happens, whereas the Checkout UI library provides the checkout flow primitives that you mount inside that surface.

Related agent UI libraries

Agentic checkout is typically embedded into one of Constructor’s agent UI libraries:

AI Shopping Assistant (ASA) UI library
- GitHub: Constructor-io/constructorio-ui-asa
- npm: @constructor-io/constructorio-ui-asa
- Storybook: constructor-io.github.io/constructorio-ui-asa
Product Insights Agent (PIA) UI library
- GitHub: Constructor-io/constructorio-ui-pia
- npm: @constructor-io/constructorio-ui-pia
- Storybook: constructor-io.github.io/constructorio-ui-pia

The agent UI libraries provide the “agent surface” where the shopper interaction happens. The Checkout UI library provides the checkout flow primitives that you mount inside that surface.

Checkout UI library

For detailed integration walkthroughs (React, non-React, standalone) and the full Checkout UI library API surface (steps, routing, persistence, session lifecycle), refer to the Checkout UI library Storybook:

Checkout UI library Storybook

Key pages:

How checkout works

Your application starts a checkout flow inside the ASA or PIA UI.
The Checkout UI library calls your onCreateSession callback.
Your backend creates a Stripe Checkout Session (ui_mode: 'form') and returns { clientSecret, publishableKey }.
The UI library displays Stripe Embedded Checkout (form).
After payment, your application confirms/fulfils the order and displays confirmation.

Prepare your backend for checkout

Before you integrate Stripe via the Checkout UI library, you’ll need the following from your Stripe account and backend:

1) Create a Stripe secret key

Your backend will need a Stripe secret API key. Stripe secret keys are typically either:

Restricted secret keys (rk_*) — recommended for least-privilege integrations
Standard secret keys (sk_*) — broader access; use only if your Stripe setup requires it

Create a dedicated key for this integration and store it in your secrets manager. Copy the key value immediately as you will not be able to retrieve it later.

Recommended guidelines:

Restricted keys typically start with rk_
Give it a descriptive name, such as “Constructor Agent — Checkout”
Limit permissions to the minimum required for your implementation. At a minimum, your backend must be able to create Checkout Sessions.

2) Locate your Stripe publishable key

You will also need your Stripe publishable key (pk_test_* or pk_live_*). Your backend returns this value to the UI library as publishableKey.

3) Implement the Checkout Session creation endpoint

Your backend must expose an endpoint (e.g., POST /api/checkout-session) that:

Receives the shopper’s current cart context from your application (directly or via server-side lookup).
Creates a Stripe Checkout Session using ui_mode: 'form'.
Returns JSON with:
- clientSecret (from session.client_secret)
- publishableKey

The Checkout UI library consumes this response in onCreateSession.

Operational guidance:

Do not log secret keys or full client secrets.
Use an idempotency key to prevent duplicate checkout sessions (see the Storybook Sessions page).

4) Implement a session-update endpoint (optional)

If you support changes after session creation (e.g., shipping selection, address-based tax/shipping, cart edits, promotions), implement a backend endpoint that can update the active Stripe session and wire it to onUpdateSession.

Implementation details depend on your commerce, tax, shipping, and promotions stack.

This doc focuses on the additional Stripe configuration patterns (tax and shipping) that are commonly needed for a production-ready integration.

Additional configuration options (tax and shipping)

This article does not assume a specific tax or shipping provider. When using the Checkout UI library, you enable Stripe tax and shipping behavior by adding parameters to your server-side stripe.checkout.sessions.create(...) call, and (when needed) updating the active session via onUpdateSession.

Automatic tax calculation

If you use Stripe Tax, you can enable automatic tax calculation in the Checkout Session:

const session = await stripe.checkout.sessions.create({
  // ... other params
  automatic_tax: { enabled: true },
  shipping_address_collection: {
    allowed_countries: merchantConfig.countries,
  },
})

Notes:

You must enable Stripe Tax in your Stripe account. If using an approved third-party Stripe tax app, you will need to install that app from the Stripe Marketplace before selecting it in your Stripe account.
With third-party tax providers, requirements vary by provider and by how your catalog is mapped to tax codes.

Shipping address collection and shipping options

To collect a shipping address in checkout, set shipping_address_collection.

If you want Stripe to display multiple shipping methods, you can set shipping_options. A common pattern is:

Create the session with an address collection requirement and a placeholder shipping option.
After the shopper enters an address, recalculate available shipping methods in your backend.
Update the session via your own endpoint and wire it through onUpdateSession.

Example placeholder shipping option:

const session = await stripe.checkout.sessions.create({
  // ... other params
  shipping_address_collection: {
    allowed_countries: merchantConfig.countries,
  },
  shipping_options: [
    {
      shipping_rate_data: {
        type: 'fixed_amount',
        display_name: 'Shipping calculated at checkout',
        fixed_amount: { amount: 0, currency: merchantConfig.currency },
      },
    },
  ],
})

Important:

Your team owns carrier logic and rate calculation. Constructor does not provide a shipping-rate service.
If you implement an address-based rate service, limit the number of returned options (e.g., 3-5) for a better shopper experience.

👋 Welcome to Constructor's new and improved documentation