Create Order
Submit the cart as an order with shipping and billing details.
Updated
On this page
Overview
The checkout process has two steps: start (validate the cart and collect customer info) and complete (process payment and create the order).
Submit the cart as an order with shipping and billing details.
Updated
The checkout process has two steps: start (validate the cart and collect customer info) and complete (process payment and create the order).
Validate the cart and initiate the checkout session:
import dash from "@/lib/dash"
const result = await dash.checkout.start({
cartId: dash.cart.cartId,
email: "customer@example.com", // required for guests
acceptsMarketing: true, // optional
})
// result = {
// message: "Checkout started",
// cart_items: [...],
// customer_preview: { email, ... },
// requires_otp: true // guest must verify email
// }
start() sends an OTP to the provided email. The customer must enter this code in the complete() step. This creates their account automatically.
Submit the order with shipping details and payment:
const { order, customer } = await dash.checkout.complete({
cartId: dash.cart.cartId,
email: "customer@example.com", // required for guests
code: "482901", // OTP code (guests only)
shipping: {
first_name: "Jane",
last_name: "Doe",
address_line1: "123 Main St",
address_line2: "Apt 4B",
city: "Austin",
state: "TX",
zip_code: "78701",
country: "US",
phone: "555-0123",
shipping_rate_id: "rate_usps_ground", // from shipping rates
},
customerNotes: "Leave at door", // optional
payment_token: { // from payment processor
token: "tok_abc123",
descriptor: "Authorize.net",
},
captcha_token: "turnstile_token", // optional
})
{
"order": {
"id": "ord_abc123",
"order_number": "ORD-1042",
"status": "pending",
"subtotal": "59.98",
"shipping": "12.50",
"tax": "5.25",
"discount": "0.00",
"total": "77.73",
"items": [...],
"shipping_address": {...},
"created_at": "2025-01-15T10:30:00Z"
},
"customer": { "id": "cust_xyz", "email": "..." },
"access_token": "eyJ...", // only for new guest accounts
"refresh_token": "eyJ..." // only for new guest accounts
}
Before showing the shipping form, fetch available shipping locations:
const { countries } = await dash.checkout.getShippingLocations()
// countries = [{ id, name, code, states: [{ id, name, code }] }]
Use this to populate country and state dropdowns in your checkout form.
# Start checkout
POST /storefront/checkout/start
X-API-Key: pk_live_your_key
Content-Type: application/json
{
"cart_id": "cart_xyz",
"email": "customer@example.com"
}
# Complete checkout
POST /storefront/checkout/complete
X-API-Key: pk_live_your_key
Content-Type: application/json
{
"cart_id": "cart_xyz",
"email": "customer@example.com",
"code": "482901",
"shipping": { ... },
"payment_token": { "token": "tok_abc", "descriptor": "..." }
}
Checkout is also where shipping restrictions and payment routing are decided. How those controls work for regulated categories is the product side of these endpoints.