Build a storefront
Configure Cart credentials, approved origins, product references, and recovery.
Before you start
Create active products and prices for the same merchant and environment. Enable Cart through your merchant setup flow, ensure its managed keys exist, register the exact storefront origins, then inspect Cart readiness. Key provisioning and origin changes alter access: perform them as an authorised merchant administrator, not from your storefront.
| Credential | Where it belongs | Purpose |
|---|---|---|
| Cart publishable key | Approved browser origin | The permitted storefront surface; server resolves product prices. |
| Cart secret key | Merchant server or authorised setup CLI | Setup and server operations permitted by its scopes. |
| Merchant secret API key | Server only | Merchant REST/SDK operations; never embed in HTML. |
An origin includes scheme, hostname, and port. Register staging and production separately. A publishable key does not grant setup access; missing or mismatched origins fail closed.
Choose how to render Cart
Use the CDN drawer for a ready-made storefront. Pass the merchant reference, product UUIDs, and optional price references. The drawer sends those references to the server-priced embed endpoints. Do not send browser-supplied unit_price_minor values to that surface.
The authenticated Cart Sessions API is a different server integration and accepts its documented line-item money fields. Validate prices on your server before using it.
Capture contact and consent
Set contact with POST /v2/cart-sessions/{id}/contact using email, promotional_consent, and sms_consent. null clears a supplied value. Record the customer's actual choices; do not infer marketing consent from starting checkout or entering an email address. A recorded SMS preference does not establish that an SMS recovery service is enabled.
Listen for commerce.cart.abandoned if you operate recovery. Check consent and current Cart state before sending a recovery message. Abandonment, expiry, and conversion are different states: do not attempt to convert a closed cart or promise that an old link remains reusable. Rebuild a purchase only after revalidating products, prices, and availability.
Verify the storefront
- Allowed origin: load products, add/change/remove an item, inspect the server total, and convert once.
- Unregistered origin: confirm the browser request is refused.
- Invalid or inactive product: show a useful error without creating an incorrect total.
- Repeated convert: reconcile the returned Checkout Session instead of creating another order.
- Recovery: verify consent, an expired cart, and a cart already converted before messaging.
The upcoming CLI provides Cart readiness, origin, key, and webhook setup commands. Follow candidate CLI workflows only with a verified matching binary; the published v0.1.2 guide does not promise those commands.