Stripe and commerce settings

2026-06-01 23:16:17

Keys, webhooks, tax modes, shipping zones, and coupons.

Stripe keys

Use test keys in staging (sk_test_…, pk_test_…)
Store live keys only in production .env or encrypted admin settings
Never commit keys to git

Configure under Admin → Commerce → Commerce settings:

Stripe secret key
Stripe publishable key
Webhook signing secret

Webhooks

In Stripe Dashboard → Developers → Webhooks, add endpoint:

https://your-site.com/commerce/stripe/webhook

Subscribe to:

checkout.session.completed — Marks order paid, triggers fulfillment
checkout.session.expired — Cancels abandoned checkout orders

Webhooks fulfill inventory, digital grants, and emails if the customer never returns to the success URL.

Tax modes

Mode	Behaviour
Flat	Single `commerce_tax_rate_bps` on subtotal after coupon
Per country	Rate from Tax rates admin for cart ship-to country
Stripe Tax	`automatic_tax` on Checkout Session (enable Stripe Tax in Dashboard)

Shipping zones

Create zones under Admin → Shipping with ISO country codes (comma-separated).
Leave countries empty on one zone for rest-of-world fallback.
Enable Use shipping zones in Commerce settings.

Flat-rate fields remain fallback when zones are disabled. When shipping is enabled, Checkout collects shipping address for allowed countries.

Coupons

Manage under Commerce → Coupons. Coupons apply to cart lines using local price_cents pricing. Products using stripe_price_id only charge via Stripe's price—coupons are disabled when such items are in the cart.

Emails and inventory

Enable customer confirmation and admin notification emails in settings
Enable inventory tracking to decrement stock_qty on paid orders
Low-stock report available in admin when tracking is on

Troubleshooting

Webhook 400 — Signing secret mismatch; verify endpoint URL is exact.
Order stuck pending — Webhook not received; check Stripe event log and server firewall.
Tax wrong at checkout — Confirm ship-to country selected on cart matches tax rate table.