checkout-flow

name	checkout-flow
description	Use when creating, updating, reviewing, or debugging checkout, order creation, payment flow, inventory validation, order state, checkout forms, payment webhooks, or checkout-related failures.

Checkout Flow

Use this skill for safe checkout, payment, order, and inventory flows.

Rules

• Follow the project’s existing checkout, cart, order, payment, and inventory patterns.
• Do not add a new payment provider, order model, inventory model, queue system, or state machine unless already used or explicitly requested.
• Never trust client-provided prices, totals, discounts, taxes, shipping, stock, payment status, ownership, or permissions.
• Load cart data from trusted server-side state.
• Recalculate totals server-side before payment.
• Validate product existence, availability, stock, and permissions at checkout.
• Create an order snapshot when the project supports orders.
• Create payment sessions/intents idempotently.
• Do not mark orders as paid from client confirmation alone.
• Verify payment webhooks before updating order, payment, or inventory state.
• Use transactions or safe atomic updates for critical order/inventory changes.
• Preserve existing response, error, logging, and test patterns.
• Avoid unrelated refactors.

Inspect First

Before changing checkout code, check existing patterns for:

• cart flow
• order model/statuses
• payment provider
• webhook handling
• inventory/reservation logic
• pricing, discount, tax, and shipping logic
• ownership/permission checks
• timeout/recovery behavior
• test style

Implementation Checklist

• Validate checkout input.
• Fetch the cart from trusted server-side state.
• Reject empty or invalid carts.
• Revalidate products, prices, stock, and permissions.
• Recalculate final totals server-side.
• Create or update the order using trusted snapshot data.
• Create payment session/intent with idempotency.
• Store provider IDs when the project does this.
• Handle payment result through verified provider flow.
• Commit or release inventory safely.
• Add or update relevant tests.

Pricing Rules

• Ignore client-provided prices and totals.
• Use trusted product, discount, tax, and shipping logic.
• Revalidate totals before payment creation.
• Handle price changes according to project behavior.
• Do not expose internal pricing or provider errors.

Inventory Rules

• Validate stock before payment.
• Prevent overselling with existing lock, reservation, transaction, or atomic update patterns.
• Release reserved inventory on payment failure, cancellation, or timeout when supported.
• Commit inventory only after verified successful payment/order state.

Payment and Webhook Rules

• Use the existing payment integration.
• Use idempotency for payment creation and webhook processing.
• Verify webhook signatures before trusting events.
• Ignore duplicate webhook events safely.
• Keep webhook handlers small.
• Do not log card data, tokens, client secrets, webhook secrets, or sensitive provider payloads.

Order State Rules

• Follow existing order statuses.
• Do not invent new statuses if the project already has them.
• Prevent invalid transitions.
• Keep order, payment, and inventory state consistent.
• Make retries safe.
• Do not leave paid orders stuck in pending if verified payment success exists.

Access Rules

• Users must not checkout another user’s cart.
• Users must not access another user’s order or payment session.
• Organization or tenant checkout must verify membership and permissions.
• Do not trust customer, user, tenant, plan, or role values from the client.

Failure Handling

• Invalid input: fail safely.
• Empty cart: reject checkout.
• Product unavailable or insufficient stock: return conflict-style error.
• Payment provider failure: return safe error and keep state recoverable.
• Expired checkout: release reservation if supported.
• Duplicate webhook: skip safely.
• Partial failure: avoid inconsistent order/payment/inventory state.

Tests

Cover relevant paths:

• successful checkout
• empty cart
• invalid checkout input
• product unavailable
• insufficient stock
• server-side total recalculation
• payment creation failure
• successful payment webhook
• failed payment webhook
• duplicate webhook
• expired checkout/reservation
• unauthorized checkout
• inventory commit/release