Carts, Checkout & Online Payments

Overview

A sale in StretchShop flows through a cart and then a checkout that produces an order. Along the way you can add items, apply a shipping address and rate, apply discount codes and gift cards, and — with payments enabled — charge the buyer securely through Stripe. This guide walks the full path.

The cart lifecycle

1. Start a cart. Create a new cart, optionally attaching a customer and choosing a currency (default CAD). A cart must be open to be changed.
2. Add items. Add a product or variant with a quantity (defaults to 1). The cart tracks a running subtotal, item count, and any applied discounts.
3. Update or remove items. Change a line's quantity (must be positive) or remove it. Use Clear to empty the cart.

Address, shipping, and delivery

1. Add a shipping address to the cart — name, line 1, city, country (a two-letter code like CA), and region/postal code as needed. This is required to check out physical, stock-tracked items.
2. Get shipping rates. StretchShop computes the applicable rates for the cart's address, subtotal, and item count, and applies any free-shipping discount.
3. Select a shipping rate. Choose one of the returned options; the chosen rate's cost is added to the order.
4. Optionally set a delivery method (for example standard vs. express) where configured.

Discounts and gift cards

• Apply a discount code to an open, non-empty cart. StretchShop validates the code (active, in date, within usage limits, meets minimum subtotal, and applicable to the cart's items) and reflects the savings in the totals. Remove a code at any time.
• Gift cards can be looked up by code and used to pay down an order balance (see Discounts, Codes & Gift Cards).

Checkout

When the cart is ready, run Checkout. StretchShop validates everything in one atomic step:

• The cart is open and not empty.
• All items share the cart currency.
• Applied discounts are still valid.
• A shipping address and rate exist for physical, tracked items.
• Tax is computed for the destination.
• Stock is reserved so you never oversell.

On success, checkout creates an order (starting pending, or paid when payment is captured) and returns the order with its line items, discounts, shipping, and tax. Checkout supports an idempotency key so a retried request never creates a duplicate order — replaying the same key returns the original order.

Taking real payments (Stripe)

If online payments are enabled for your workspace, StretchShop uses Stripe Connect:

1. Connect your account. Open payment setup and complete Stripe onboarding via the link StretchShop provides. Until Stripe reports your account can accept charges, live payment attempts are blocked.
2. Create a payment intent for the cart. StretchShop returns a client secret your storefront uses to collect card details securely. A small platform fee may apply.
3. Confirm the payment. When Stripe confirms success, a secure webhook checks the cart out with the payment's idempotency key, marks the order paid, and clears the stored client secret. Failed or canceled payments mark the intent accordingly and leave stock unreserved.

A realistic example

A buyer adds two candles ($24.00 each) to a cart. You add their Toronto address, fetch shipping rates, and select Standard ($8.00). They enter code WELCOME10 for 10% off. The cart shows subtotal $48.00, discount −$4.80, shipping $8.00, plus tax. You create a payment intent, the buyer pays by card, Stripe confirms, and the webhook produces a paid order — inventory drops by two automatically.

Tips

• Always send an idempotency key from your checkout button so double-clicks and retries can't create duplicate orders.
• Collect the shipping address first for physical goods — rates and tax depend on it.
• Test end to end in a safe mode before going live so you see the full cart → intent → webhook → paid flow.

Troubleshooting

• "Cart not open" — the cart was already checked out or cleared; start a new cart.
• "Shipping address required" / "Shipping rate required" — add the address and select a rate before checking out physical items.
• "Shipping rate not applicable" — the selected rate doesn't cover the cart's address; refetch rates and pick a valid one.
• "Insufficient stock" — reduce the quantity or restock; the response tells you the available vs. requested amount.
• "Idempotency key reused" — that key already produced an order; read back the existing order instead of retrying with the same key.
• Payments disabled / account restricted — online payments aren't enabled or Stripe onboarding isn't complete; finish onboarding or contact your administrator.