Checkout Flow

The checkout process converts a shopping basket into an order through a multi-step session.

Complete Flow

Step 1: Create Checkout Session

POST /api/storefront/checkout/session
Authorization: Bearer <token>
Content-Type: application/json

{
  "basketId": "basket-uuid",
  "shippingAddress": {
    "firstName": "John",
    "lastName": "Doe",
    "addressLine1": "123 Main St",
    "city": "New York",
    "stateProvince": "NY",
    "postalCode": "10001",
    "countryCode": "US",
    "phone": "+1234567890"
  },
  "billingAddress": {
    "sameAsShipping": true
  }
}

Response:

{
  "sessionId": "guid",
  "items": [...],
  "subTotal": 59.98,
  "promotionDiscount": 12.00,
  "discountCodeDiscount": 0,
  "availableShippingMethods": [
    { "id": "guid", "name": "Standard Shipping", "cost": 5.99, "estimatedDays": "3-5" },
    { "id": "guid", "name": "Express Shipping", "cost": 14.99, "estimatedDays": "1-2" }
  ],
  "availablePaymentMethods": ["stripe", "iyzico"]
}

Step 2: Select Shipping Method

PUT /api/storefront/checkout/session/{sessionId}/shipping
Content-Type: application/json

{
  "shippingMethodId": "guid"
}

Step 3: Select Payment Method

PUT /api/storefront/checkout/session/{sessionId}/payment
Content-Type: application/json

{
  "paymentMethod": "stripe"
}

Step 4: Confirm & Pay

POST /api/storefront/checkout/session/{sessionId}/confirm

This creates the order and initiates the payment. The response includes the payment provider's client secret for completing payment on the frontend.

Step 5: Confirm Payment

After the user completes payment on the client side (e.g., via Stripe.js):

POST /api/storefront/payments/confirm
Content-Type: application/json

{
  "sessionId": "guid",
  "paymentIntentId": "pi_..."
}

Checkout Session Fields

Field	Description
subTotal	Sum of item prices before discounts
promotionDiscount	Automatic promotion discount amount
discountCodeDiscount	Applied discount code amount
shippingCost	Selected shipping method cost
taxAmount	Calculated tax
totalAmount	Final amount to charge

Important Notes

Authentication Required

All checkout endpoints require a valid JWT token. Guest checkout is not supported — users must register/login first.

Shipping Methods

Available shipping methods depend on the store configuration and the shipping address country. Fetch them as part of the checkout session creation.

Promotions in Checkout

Automatic promotions (including free shipping promotions) are re-evaluated during checkout. If a promotion grants free shipping, the shippingCost will be 0 and hasFreeShipping will be true.