Skip to main content

Checkout Quick Start

This guide walks you through the essential steps to implement a basic checkout flow using a manual payment gateway and the customer object method. This is the simplest and easiest to implement form of checkout available in Elastic Path, so it's ideal to help you understand the basic concepts.

You'll learn how to:

  • Convert a cart to an order using the customer object method
  • Process payment with a manual gateway
  • Display order confirmation

For other checkout methods or payment options, refer to our dedicated guides linked at the bottom of this page.

Prerequisites​

  • A JavaScript application with Elastic Path SDK installed
  • @epcc-sdk/sdks-shopper package configured with your client credentials
  • A cart with items (see the Cart Management Quick Start)
npm install @epcc-sdk/sdks-shopper

Step 1: Collect Customer Information​

For this quickstart, we'll checkout a cart using a customer object. A customer object contains the shopper's basic information needed for checkout, such as name, email, and address. This might commonly be thought of as a 'guest checkout'. It's the most flexible checkout method and doesn't require authentication tokens or stored customer IDs.

import { getCartId } from "@epcc-sdk/sdks-shopper";

// Collect customer information from a form
const collectCustomerInfo = (formData) => {
  // Create a structured customer object for checkout
  return {
    customer: {
      email: formData.email,
      name: `${formData.firstName} ${formData.lastName}`,
    },
    billing_address: {
      first_name: formData.billingFirstName || formData.firstName,
      last_name: formData.billingLastName || formData.lastName,
      company_name: formData.billingCompany || "",
      line_1: formData.billingLine1,
      line_2: formData.billingLine2 || "",
      city: formData.billingCity,
      county: formData.billingCounty || "",
      region: formData.billingRegion || "",
      postcode: formData.billingPostcode,
      country: formData.billingCountry,
    },
    shipping_address: {
      first_name: formData.shippingFirstName || formData.firstName,
      last_name: formData.shippingLastName || formData.lastName,
      company_name: formData.shippingCompany || "",
      phone_number: formData.shippingPhone || "",
      line_1: formData.shippingLine1,
      line_2: formData.shippingLine2 || "",
      city: formData.shippingCity,
      county: formData.shippingCounty || "",
      region: formData.shippingRegion || "",
      postcode: formData.shippingPostcode,
      country: formData.shippingCountry,
      instructions: formData.shippingInstructions || "",
    },
  };
};

Step 2: Convert Cart to Order​

When a cart is ready for checkout, convert it to an order through the checkout process:

import { checkoutApi, getCartId } from "@epcc-sdk/sdks-shopper";

// Checkout the cart to create an order
const checkoutCart = async (customerData) => {
  const cartId = getCartId();

  if (!cartId) {
    throw new Error("No cart found");
  }

  try {
    const response = await checkoutApi({
      path: {
        cartID: cartId,
      },
      body: {
        data: customerData,
      },
    });

    return response.data;
  } catch (error) {
    console.error("Checkout failed:", error);
    throw error;
  }
};

Step 3: Process Payment with Manual Gateway​

For this quickstart, we'll use a manual payment gateway:

import { paymentSetup } from "@epcc-sdk/sdks-shopper";

// Process payment using a manual gateway
const processPayment = async (orderId) => {
  try {
    const response = await paymentSetup({
      path: {
        orderID: orderId,
      },
      body: {
        data: {
          gateway: "manual",
          method: "purchase",
        },
      },
    });

    return response.data;
  } catch (error) {
    console.error("Payment processing failed:", error);
    throw error;
  }
};

Step 4: Order Confirmation​

Display order confirmation to the customer and clear the cart:

// Handle order completion
const completeOrder = (orderData) => {
  // Clear cart ID and other checkout related data
  localStorage.removeItem("ep_cart_id");

  // Return order information for confirmation page
  return {
    orderId: orderData.id,
    orderReference: orderData.reference,
    orderStatus: orderData.status,
    orderTotal: orderData.meta?.display_price?.with_tax?.formatted,
  };
};

Complete Example​

Here's how to put it all together in a simple React component:

import React, { useState } from "react";
import { getCartId, checkoutApi, paymentSetup } from "@epcc-sdk/sdks-shopper";

function SimpleCheckout() {
  const [formData, setFormData] = useState({
    email: "",
    firstName: "",
    lastName: "",
    billingLine1: "",
    billingCity: "",
    billingPostcode: "",
    billingCountry: "",
    // Add more fields as needed
  });
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState(null);
  const [orderConfirmation, setOrderConfirmation] = useState(null);

  const handleInputChange = (e) => {
    const { name, value } = e.target;
    setFormData((prev) => ({ ...prev, [name]: value }));
  };

  const handleSubmit = async (e) => {
    e.preventDefault();
    setLoading(true);
    setError(null);

    try {
      // Step 1: Prepare customer data
      const customerData = {
        customer: {
          email: formData.email,
          name: `${formData.firstName} ${formData.lastName}`,
        },
        billing_address: {
          first_name: formData.firstName,
          last_name: formData.lastName,
          line_1: formData.billingLine1,
          city: formData.billingCity,
          postcode: formData.billingPostcode,
          country: formData.billingCountry,
        },
        shipping_address: {
          first_name: formData.firstName,
          last_name: formData.lastName,
          line_1: formData.billingLine1,
          city: formData.billingCity,
          postcode: formData.billingPostcode,
          country: formData.billingCountry,
        },
      };

      // Step 2: Checkout the cart
      const cartId = getCartId();
      const checkoutResponse = await checkoutApi({
        path: {
          cartID: cartId,
        },
        body: {
          data: customerData,
        },
      });

      const orderId = checkoutResponse.data?.data?.id;

      // Step 3: Process payment
      const paymentResponse = await paymentSetup({
        path: {
          orderID: orderId,
        },
        body: {
          data: {
            gateway: "manual",
            method: "purchase",
          },
        },
      });

      // Step 4: Order confirmation
      const orderData = paymentResponse.data?.data;

      // Clear cart and set confirmation
      localStorage.removeItem("ep_cart_id");
      setOrderConfirmation({
        orderId: orderData.order.id,
        orderReference: orderData.order.reference,
        orderStatus: orderData.order.status,
      });
    } catch (err) {
      setError("Checkout failed. Please try again.");
      console.error(err);
    } finally {
      setLoading(false);
    }
  };

  if (orderConfirmation) {
    return (
      <div className="order-confirmation">
        <h2>Order Confirmed!</h2>
        <p>Order ID: {orderConfirmation.orderId}</p>
        <p>Reference: {orderConfirmation.orderReference}</p>
        <p>Status: {orderConfirmation.orderStatus}</p>
      </div>
    );
  }

  return (
    <form onSubmit={handleSubmit}>
      <h2>Checkout</h2>
      {error && <div className="error">{error}</div>}

      <div className="form-group">
        <label htmlFor="email">Email</label>
        <input
          type="email"
          id="email"
          name="email"
          value={formData.email}
          onChange={handleInputChange}
          required
        />
      </div>

      <div className="form-group">
        <label htmlFor="firstName">First Name</label>
        <input
          type="text"
          id="firstName"
          name="firstName"
          value={formData.firstName}
          onChange={handleInputChange}
          required
        />
      </div>

      {/* Add more form fields for lastName, billing address, etc. */}

      <button type="submit" disabled={loading}>
        {loading ? "Processing..." : "Complete Checkout"}
      </button>
    </form>
  );
}

Next Steps​

Now that you've implemented a basic checkout flow, explore these advanced topics:

tip

For a complete example, check out the SPA Checkout Example in the Elastic Path Composable Frontend repository.