Persist Cart Across Sessions
This guide explains how to maintain cart state when customers leave and return to your store.
Built-in Persistence with initializeCart
The Elastic Path SDK provides a built-in utility called initializeCart
that handles cart persistence automatically:
import { initializeCart, getCartId } from "@epcc-sdk/sdks-shopper";
// Get or create a cart, automatically persisted in localStorage
const cartId = await initializeCart();
// Retrieve the cart ID without creating a new cart
const existingCartId = getCartId();
// Use custom storage key if needed
const cartIdWithCustomKey = await initializeCart({
storageKey: "my-custom-cart-key",
});
The initializeCart
utility:
- Checks localStorage for an existing cart ID
- Returns it if found
- Creates a new cart via the API if not found
- Automatically stores the new cart ID in localStorage
- Returns the cart ID for immediate use
This is the recommended approach for most applications as it handles persistence seamlessly.
Custom Client-Side Storage Options
For more control or specific use cases, you may want to implement your own persistence strategy:
Using localStorage
A custom implementation using localStorage:
import { manageCarts } from "@epcc-sdk/sdks-shopper";
// Cart ID storage key
const CART_ID_KEY = "ep_cart_id";
// Create a cart and persist the ID
const createAndPersistCart = async () => {
// Create a new cart
const response = await manageCarts({
path: {
cartID: "create",
},
body: {
data: {},
},
});
const cartId = response.data.data.id;
// Store the cart ID in localStorage
localStorage.setItem(CART_ID_KEY, cartId);
return cartId;
};
// Get the persisted cart ID
const getCartId = () => {
return localStorage.getItem(CART_ID_KEY);
};
// Helper to check if we have a stored cart
const hasStoredCart = () => {
return !!getCartId();
};
// Remove the cart ID (e.g., after order completion)
const clearCartId = () => {
localStorage.removeItem(CART_ID_KEY);
};
Using Cookies
For multi-domain applications, cookies may be a better choice:
import { Cookies } from "react-cookie";
import { manageCarts } from "@epcc-sdk/sdks-shopper";
// Initialize cookies
const cookies = new Cookies();
// Cart ID cookie name
const CART_ID_COOKIE = "ep_cart_id";
// Create a cart and persist the ID in a cookie
const createAndPersistCart = async () => {
// Create a new cart
const response = await manageCarts({
path: {
cartID: "create",
},
body: {
data: {},
},
});
const cartId = response.data.data.id;
// Store the cart ID in a cookie (30 days expiration)
cookies.set(CART_ID_COOKIE, cartId, {
path: "/",
maxAge: 30 * 24 * 60 * 60, // 30 days in seconds
sameSite: "lax",
});
return cartId;
};
// Get the persisted cart ID
const getCartId = () => {
return cookies.get(CART_ID_COOKIE);
};
Comparison of Persistence Methods
Method | Pros | Cons | Best for |
---|---|---|---|
Built-in SDK | Simplest implementation, handles edge cases | Less customizable | Most applications |
localStorage | Larger storage capacity, simpler API | Not shared across domains, no expiration | Single-domain sites |
Cookies | Works across subdomains, server accessible | Size limitations, included in requests | Multi-domain ecosystems |
Security Considerations
- Data minimization: Store only what's necessary (cart ID, not full cart data)
- No sensitive information: Never store payment details or personal information
- HTTPS only: Ensure your site uses HTTPS to protect stored data
Implementation for Different Platforms
- React/Next.js: Use
useState
anduseEffect
hooks with localStorage - Server-Side Rendering: Access cookies on the server to maintain cart state
- Mobile apps: Use AsyncStorage (React Native) or equivalent native storage
// Example React hook for cart persistence
function useCart() {
const [cartId, setCartId] = useState(() => {
// Initialize from localStorage (runs only on client)
if (typeof window !== "undefined") {
return localStorage.getItem(CART_ID_KEY) || null;
}
return null;
});
// Persist cart ID to localStorage when it changes
useEffect(() => {
if (cartId) {
localStorage.setItem(CART_ID_KEY, cartId);
} else {
localStorage.removeItem(CART_ID_KEY);
}
}, [cartId]);
return { cartId, setCartId };
}
tip
For a real-world implementation of cart persistence, see the SPA Cart Example on GitHub.