Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.shopi.lk/llms.txt

Use this file to discover all available pages before exploring further.

shop.checkout.createOrder(params)

Places an order. Call this when the customer confirms checkout.
const order = await shop.checkout.createOrder({
  customer_name: 'John Doe',
  customer_email: 'john@example.com',
  customer_phone: '+94771234567',
  items: [
    {
      product_id: 'uuid-here',
      name: 'Red Cotton T-Shirt',
      price: 2500,
      quantity: 2,
      image: 'https://...',
      variant: 'Size: L',
    },
  ],
  shipping_address: {
    line1: '42 Galle Road',
    city: 'Colombo',
    country: 'LK',
  },
  payment_method: 'cod',
});

console.log(order.order_number); // e.g. "ORD-M3X9K-AB12"

Parameters

ParamTypeRequiredDescription
customer_namestringFull name
customer_emailstringEmail address
customer_phonestringPhone number
itemsCartItem[]At least one item required
shipping_addressobjectDelivery address
shipping_methodstringSelected shipping method
payment_methodstringDefault: 'cod'
notesstringOrder notes from customer
promo_code_idstringID from validatePromo result
discount_amountnumberDiscount value from validatePromo

CartItem type

{
  product_id: string;  // UUID
  name: string;        // product name at time of purchase
  price: number;       // unit price
  quantity: number;
  image?: string;      // image URL
  variant?: string;    // e.g. "Color: Red, Size: L"
}

Response

{
  id: string;
  order_number: string;  // human-readable, e.g. "ORD-M3X9K-AB12"
  total: number;
  status: string;        // "pending"
  created_at: string;
}

Example — Full checkout flow

import { Shopi, ShopiError } from '@shopi-lk/storefront-sdk';

const shop = new Shopi({ apiKey: process.env.SHOPI_API_KEY! });

async function placeOrder(cart: CartItem[], formData: CheckoutForm) {
  // 1. Optionally validate promo first
  let promoResult = null;
  if (formData.promoCode) {
    promoResult = await shop.checkout.validatePromo({
      code: formData.promoCode,
      cart_items: cart,
      subtotal: cart.reduce((s, i) => s + i.price * i.quantity, 0),
    });
  }

  // 2. Place the order
  try {
    const order = await shop.checkout.createOrder({
      customer_name: formData.name,
      customer_email: formData.email,
      customer_phone: formData.phone,
      items: cart,
      shipping_address: formData.address,
      payment_method: formData.paymentMethod,
      notes: formData.notes,
      promo_code_id: promoResult?.valid ? promoResult.promo_code?.id : undefined,
      discount_amount: promoResult?.valid ? promoResult.discount_amount : undefined,
    });

    // 3. Redirect to confirmation
    window.location.href = `/order-confirmed?ref=${order.order_number}`;
  } catch (error) {
    if (error instanceof ShopiError) {
      showError(`Order failed: ${error.message}`);
    }
  }
}
Always snapshot the product name and price at checkout time into the items array. Do not rely on re-fetching prices at order creation — prices may change.