DocumentationCheckout & Invoices

Checkout & Invoices

5 minLast updated: 2026-03-31

Atomic Checkout Flow

The entire checkout runs in a single database transaction. If any step fails, everything rolls back, no partial orders:

  1. Validate cart: Check all items are still available and prices match
  2. Stock check: Verify sufficient inventory for all items
  3. Addresses: Validate billing and shipping addresses
  4. Shipping: Calculate shipping cost based on zone and weight
  5. Reserve stock: Atomically decrement inventory (SELECT...FOR UPDATE)
  6. Create order: Generate order with line items and totals
  7. Generate invoice: Create invoice with unique sequential number
  8. Generate PDF: Render invoice as downloadable PDF
  9. Apply discount: Record discount code usage if applicable
  10. Clear cart: Empty the customer's cart
  11. Notifications: Send order confirmation email (fire-and-forget)

Invoice Generation

Each invoice gets a unique sequential number using atomic SELECT...FOR UPDATE on the invoice sequence counter. Invoices include: store details, customer info, line items with prices, subtotal, shipping, discount, and total.

Currency follows the Balkan standard: dot for thousands separator, comma for decimals (e.g., 7.457,00 RSD).

Payment Verification

For bank transfer payments, the merchant verifies payment:

POST /api/v1/storefront/merchant/invoices/:id/verify
{
  "verified": true,
  "notes": "Payment received via bank statement"
}

Verification triggers the payment_verified workflow event and advances the order to confirmed status.

Guest vs Customer Checkout

  • Guest: Uses X-Cart-Session header. No account needed. Provides email for order updates.
  • Customer: Authenticated with customer JWT. Saved addresses auto-fill. Order history available in account.

Was this article helpful?