> ## Documentation Index
> Fetch the complete documentation index at: https://docs.komerza.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Checkout
> Process orders and redirect customers to hosted checkout
## Overview
The `checkout()` function creates an order from the current basket and automatically redirects the customer to Komerza's hosted checkout page to complete payment.
The checkout function validates the basket, creates an order, and
**automatically redirects** to the payment page. No manual redirect handling
needed.
## Basic Usage
```javascript theme={null}
const response = await komerza.checkout(emailAddress, couponCode);
```
### Parameters
Customer's email address for the order. Must be a valid email format.
Optional coupon/discount code to apply to the order. Must be 3-32 characters
if provided.
### Returns
Returns a Promise that resolves to `ApiResponse`:
```typescript theme={null}
interface ApiResponse {
success: boolean; // Whether the order was created
message?: string; // Error message if failed
invalidFields?: Array<{
// Validation errors if any
fieldName: string;
reason: string;
}>;
data?: Order; // Order details if successful
}
```
If `success` is `true`, the browser will automatically redirect to the
checkout page. The response is mainly useful for error handling.
## Validation
The checkout function performs validation before creating the order:
**Basket Validation:**
* Basket cannot be empty
* All items must have valid product and variant IDs
**Email Validation:**
* Must be a valid email address format
**Coupon Validation (if provided):**
* Must be at least 3 characters
* Cannot exceed 32 characters
## Simple Example
```javascript theme={null}
// Checkout button handler
async function handleCheckout() {
const email = document.getElementById("email").value;
const coupon = document.getElementById("coupon").value;
try {
const response = await komerza.checkout(email, coupon);
// Only executes if checkout failed (no redirect occurred)
if (!response.success) {
alert(response.message || "Checkout failed");
}
} catch (error) {
console.error("Checkout error:", error);
alert("An error occurred during checkout");
}
}
```
## Complete Example with Validation
```html theme={null}
Checkout
```
## Error Handling
Common error scenarios and how to handle them:
### Empty Basket
```javascript theme={null}
const response = await komerza.checkout(email);
if (!response.success && response.message === "Basket is empty") {
alert("Please add items to your cart before checking out");
}
```
### Validation Errors
```javascript theme={null}
const response = await komerza.checkout(email, coupon);
if (!response.success && response.invalidFields) {
response.invalidFields.forEach((field) => {
console.log(`${field.fieldName}: ${field.reason}`);
// Display error next to the relevant form field
});
}
```
### General Errors
```javascript theme={null}
try {
await komerza.checkout(email, coupon);
} catch (error) {
// Network error or other exception
console.error("Checkout failed:", error);
alert("Could not complete checkout. Please check your connection.");
}
```
## Response Object
The `Order` object in the response contains:
```typescript theme={null}
interface Order {
id: string; // Order ID
status: string; // Order status (e.g., "pending")
amount: number; // Total amount
amountPaid: number; // Amount paid so far
currencyCode: string; // Currency (e.g., "USD")
gateway: string; // Payment gateway used
items: LineItem[]; // Order line items
customer: {
emailAddress: string;
countryCode: string;
};
gatewayMetadata?: {
clientSecret?: string; // Payment URL/secret
transactionId?: string;
// ... other gateway-specific fields
};
coupon?: {
code: string;
percentageDecrease?: number;
netDecrease: number;
};
dateCreated: string; // ISO 8601 timestamp
}
```
## Affiliate Tracking
The checkout function automatically includes affiliate tracking if an affiliate cookie (`kmrza_ref`) is present:
```javascript theme={null}
// Affiliate ID is automatically read from cookies
// No manual handling required
await komerza.checkout(email);
```
The affiliate cookie is set when customers visit your store through an affiliate link.
## Best Practices
**Validate before submission** - Check email format client-side for instant feedback
**Create basket backups** - Save basket state before checkout to restore if payment fails
**Disable during processing** - Prevent double-submissions by disabling the checkout button
**Handle all error cases** - Account for empty basket, validation errors, and network failures
**Show loading states** - Display progress indicators while checkout is processing
**Don't auto-clear basket** - The basket persists after checkout - clear it manually after payment confirmation if needed
## Next Steps
Learn how to manage cart items
Display and fetch product information