Create Order

Submit the cart as an order with shipping and billing details.

Updated September 8, 2026

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).

Step 1: Start Checkout

Validate the cart and initiate the checkout session:

typescript

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
// }

Guest Checkout: For non-authenticated customers, start() sends an OTP to the provided email. The customer must enter this code in the complete() step. This creates their account automatically.

Step 2: Complete Checkout

Submit the order with shipping details and payment:

typescript

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 Response

json

{
  "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
}

Important: For guest checkouts, the response includes auth tokens. Store these to keep the customer logged in after their order.

Get Shipping Locations

Before showing the shipping form, fetch available shipping locations:

typescript

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.

REST API

shell

# 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": "..." }
}

Next Steps

Payment Processing — Tokenizing card data
Order Confirmation — Building the confirmation page
Shipping Rates — Getting rate quotes
Recipe: Build a Checkout Flow — Full walkthrough

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.

Create Order

Submit the cart as an order with shipping and billing details.

Updated September 8, 2026

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).

Step 1: Start Checkout

Validate the cart and initiate the checkout session:

typescript

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
// }

Step 2: Complete Checkout

Submit the order with shipping details and payment:

typescript

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 Response

json

{
  "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
}

Important: For guest checkouts, the response includes auth tokens. Store these to keep the customer logged in after their order.

Get Shipping Locations

Before showing the shipping form, fetch available shipping locations:

typescript

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.

REST API

shell

# 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": "..." }
}

Next Steps

Payment Processing — Tokenizing card data
Order Confirmation — Building the confirmation page
Shipping Rates — Getting rate quotes
Recipe: Build a Checkout Flow — Full walkthrough

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.