Checkout

npm install @commercengine/checkout

Cart → OTP login/register → address → deliverability → fulfilment
→ discounts → payment method → create order → payment → status → confirmation

const { data, error, response } = await sdk.cart.getUserCart();

if (response?.status === 404) {
  // Return to shopping; this session has no active cart.
  return;
}

if (error) throw new Error(error.message);
if (!data?.cart) throw new Error("Cart response did not include a cart");

const cart = data.cart;

const loggedIn = await sdk.isLoggedIn();
if (!loggedIn) {
  // Show OTP login or open Hosted Checkout auth.
}

const { data: addressData, error: addressError } =
  await sdk.customer.createAddress({
    first_name: "Asha",
    last_name: "Sharma",
    email: "asha@example.com",
    phone: "9876543210",
    country_code: "+91",
    address_line1: "123 Market Road",
    address_line2: "",
    city: "Mumbai",
    state: "Maharashtra",
    pincode: "400001",
    country: "India",
  });

if (addressError) throw new Error(addressError.message);
const addressId = addressData?.address?.id;

const { data: updatedCart, error } = await sdk.cart.updateCartAddress(
  { id: cart.id },
  {
    shipping_address_id: addressId,
    billing_address_id: addressId,
  },
);

if (error) throw new Error(error.message);

const { data, error } = await sdk.cart.checkPincodeDeliverability({
  cart_id: cart.id,
  delivery_pincode: selectedAddress.pincode,
});

if (error) throw new Error(error.message);

if (!data?.is_serviceable) {
  // Show unserviceable items and request another address.
}

const { data, error } = await sdk.cart.getFulfillmentOptions({
  cart_id: cart.id,
});

if (error) throw new Error(error.message);

const { data, error } = await sdk.cart.updateFulfillmentPreference(
  { id: cart.id },
  {
    fulfillment_type: "delivery",
    shipments: selections.map((selection) => ({
      id: selection.shipmentId,
      shipping_provider_id: selection.shippingMethodId,
      ...(selection.courierId
        ? { courier_company_id: selection.courierId }
        : {}),
    })),
  },
);

await sdk.cart.updateFulfillmentPreference(
  { id: cart.id },
  {
    fulfillment_type: "collect-in-store",
    pickup_location_id: selectedLocationId,
  },
);

const { data, error } = await sdk.payments.listPaymentMethods({
  payment_provider_slug: "juspay",
});

if (error) throw new Error(error.message);

const { data, error } = await sdk.order.createOrder({
  cart_id: cart.id,
  payment_method: {
    payment_provider_slug: "juspay",
    integration_type: "hyper-checkout",
    action: "paymentPage",
    gateway_reference_id: gatewayReferenceId,
    return_url: `${window.location.origin}/checkout/return`,
  },
});

if (error) throw new Error(error.message);

const orderNumber = data?.order?.order_number;
if (!orderNumber) throw new Error("Order response did not include an order number");

sessionStorage.setItem("pending_order_number", orderNumber);

if (!data?.payment_required) {
  showOrderConfirmation(data?.order);
} else {
  window.location.assign(data.payment_info.payment_links.web);
}

const MAX_POLLS = 40;
const POLL_INTERVAL_MS = 3_000;

async function waitForPayment(orderNumber: string) {
  for (let attempt = 0; attempt < MAX_POLLS; attempt += 1) {
    const { data, error, response } =
      await sdk.order.getPaymentStatus(orderNumber);

    if (error) {
      const status = response?.status;
      const retryable =
        status === undefined ||
        status === 408 ||
        status === 429 ||
        (status >= 500 && status < 600);

      if (!retryable) throw new Error(error.message);

      await new Promise((resolve) =>
        setTimeout(resolve, POLL_INTERVAL_MS),
      );
      continue;
    }

    if (!data) throw new Error("Payment status response was empty");
    if (data.status === "success" || data.status === "failed") return data;

    if (
      data.status !== "pending" &&
      data.status !== "partially_paid"
    ) {
      return data;
    }

    await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
  }

  return null;
}

const { data, error } = await sdk.order.retryOrderPayment(
  { order_number: orderNumber },
  {
    payment_method: {
      payment_provider_slug: "juspay",
      integration_type: "hyper-checkout",
      action: "paymentPage",
      gateway_reference_id: gatewayReferenceId,
      return_url: `${window.location.origin}/checkout/return`,
    },
  },
);

if (error) throw new Error(error.message);

[ ] Hosted Checkout considered before custom build
[ ] user logged in before custom checkout
[ ] active cart refetched after login
[ ] saved address created/selected and linked by ID
[ ] returned cart totals used after address update
[ ] deliverability checked with current cart operation
[ ] every shipment has a valid fulfilment selection
[ ] existing preference restored on refresh
[ ] payment methods discovered, not hardcoded
[ ] order number persisted before redirect
[ ] payment status verified through Commerce Engine
[ ] pending status has bounded polling and recovery UI
[ ] retry shown only when allowed
[ ] duplicate order/payment submissions prevented
[ ] checkout analytics events have one owner and use canonical CE entities
[ ] provider credentials and payment data never logged