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:
- Validate cart: Check all items are still available and prices match
- Stock check: Verify sufficient inventory for all items
- Addresses: Validate billing and shipping addresses
- Shipping: Calculate shipping cost based on zone and weight
- Reserve stock: Atomically decrement inventory (SELECT...FOR UPDATE)
- Create order: Generate order with line items and totals
- Generate invoice: Create invoice with unique sequential number
- Generate PDF: Render invoice as downloadable PDF
- Apply discount: Record discount code usage if applicable
- Clear cart: Empty the customer's cart
- 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-Sessionheader. No account needed. Provides email for order updates. - Customer: Authenticated with customer JWT. Saved addresses auto-fill. Order history available in account.