commerce trained

The learned layer of the commerce guru: how a payment commits, and what a local test can never prove.

mental model

Checkout starts a provider flow; a signed, deduplicated provider event commits a local entitlement. Keep provider state and product access separately queryable.

examples

const event = provider.verify(rawBody, signature, webhookSecret)
await db.transaction().execute(async (trx) => {
  const inserted = await insertProviderEvent(trx, event.id)
  if (!inserted) return
  await grantEntitlement(trx, event.data)
})

best practices

Verify before parsing or fulfilling; Stripe documents raw-body signature verification (source).
Use a provider event ID unique key; retries and duplicate delivery are normal.
Keep redirect handling informational; webhook/reconciliation owns fulfillment.

strengths

Provider checkout reduces payment-data handling; Shopify owns tightly integrated merchant and storefront surfaces.

weaknesses / pain points

Provider capabilities, legal availability, tax role, and API versions change. A local handler test cannot prove a real payment or merchant configuration.

gotchas

Parsing or reserializing a signed request can invalidate verification. Shopify versioned APIs release quarterly and versions fall forward when inaccessible (source).

known bugs

No version-specific defect is documented. Check the provider changelog before pinning a workaround.

troubleshooting

symptom	root cause	fix
payment redirect grants access	navigation treated as authority	wait for verified webhook or reconciliation
duplicate entitlement	retries reuse side effects	unique provider event ID and transactional fulfillment
signature failure	body was transformed	pass the original request bytes

practiced cases

The webhook and versioning guidance here comes from Stripe, Paddle, and Shopify primary documentation. The Shopify CLI was absent locally, so no authenticated store or sandbox flow was claimed; this evidence covers routing and source currency only.

sources

Read the commerce guide.