Add Items to Cart

This guide explains how to add various types of items to an existing shopping cart in your Elastic Path implementation.

Adding Standard Products

The manageCarts method allows you to add regular products to a customer's cart:

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

// Get the current cart ID
const cartId = getCartId();

// Add a product to cart
const response = await manageCarts({
  path: {
    cartID: cartId,
  },
  body: {
    data: {
      type: "cart_item",
      id: "product-12345",
      quantity: 1,
    },
  },
});

Adding Custom Items

Custom items are useful for items that aren't managed in your product catalog:

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

// Get the current cart ID
const cartId = getCartId();

// Add a custom item directly to the cart
const response = await manageCarts({
  path: {
    cartID: cartId,
  },
  body: {
    data: {
      type: "custom_item",
      name: "Premium Service Fee",
      sku: "service-fee-premium",
      quantity: 1,
      price: {
        amount: 1995, // $19.95 in minor units
        includes_tax: false,
      },
      description: "Premium service package fee",
    },
  },
});

Example: Adding a Gift Card

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

const cartId = getCartId();

// Add a gift card directly to the cart
const response = await manageCarts({
  path: {
    cartID: cartId,
  },
  body: {
    data: {
      type: "custom_item",
      name: "Gift Card - $50",
      sku: "giftcard-50",
      quantity: 1,
      price: {
        amount: 5000, // $50 in minor units (cents)
        includes_tax: true,
      },
      description: "Gift card for recipient@example.com",
      // Store recipient info in metadata for order processing
      metadata: {
        recipient_email: "recipient@example.com",
        gift_card_type: "digital",
        delivery_method: "email",
      },
    },
  },
});

Example: Adding a Donation

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

const cartId = getCartId();

// Add a donation directly to the cart
const response = await manageCarts({
  path: {
    cartID: cartId,
  },
  body: {
    data: {
      type: "custom_item",
      name: "Donation - Save the Forests",
      sku: "donation-save-the-forests",
      quantity: 1,
      price: {
        amount: 1000, // $10 in minor units (cents)
        includes_tax: true,
      },
      description: "Donation to Save the Forests Foundation",
    },
  },
});

Adding Subscription Items

You can add subscription products to a cart by specifying the subscription offering and plan:

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

const cartId = getCartId();

// Add a subscription item to the cart
const response = await manageCarts({
  path: {
    cartID: cartId,
  },
  body: {
    data: {
      type: "subscription_item",
      id: "5b9be99f-1c94-4ddd-9718-81adab0cc3e0", // Subscription offering ID
      quantity: 1,
      subscription_configuration: {
        plan: "40010dde-2f38-489b-8b3f-14a13cbfb431", // Plan ID
      },
    },
  },
});

The price of the subscription item in the cart reflects the cost of the subscription's initial billing period. Once the cart has been checked out and the order paid for, the subscription will be automatically created in the subscriptions service.

Adding Promotion Codes

You can apply promotions to a cart using promotion codes:

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

const cartId = getCartId();

// Add a promotion code to the cart
const response = await manageCarts({
  path: {
    cartID: cartId,
  },
  body: {
    data: {
      type: "promotion_item",
      code: "SUMMER25",
    },
  },
});

Adding Dynamic Bundles

Dynamic bundles allow customers to select from predefined component options. First, shoppers configure their bundle, then you add that configuration to the cart:

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

const cartId = getCartId();

// Add a dynamic bundle with selected components to the cart
const response = await manageCarts({
  path: {
    cartID: cartId,
  },
  body: {
    data: {
      type: "cart_item",
      id: "bundle-product-12345", // Bundle product ID
      quantity: 1,
      bundle_configuration: {
        selected_options: {
          "t-shirts": {
            // Component ID
            "red-shirt-id": 1, // Option ID and quantity
            "blue-shirt-id": 2, // Option ID and quantity
          },
          accessories: {
            "hat-id": 1,
          },
        },
      },
    },
  },
});

To include component product details in the response, you can use the include parameter:

// When fetching the cart, include component product details
const cartResponse = await getCart({
  path: {
    cartID: cartId,
  },
  query: {
    include: ["items", "component_products"],
  },
});

Adding Personalized Products

You can add products with custom text inputs for personalization:

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

const cartId = getCartId();

// Add a personalized product to the cart
const response = await manageCarts({
  path: {
    cartID: cartId,
  },
  body: {
    data: {
      type: "cart_item",
      id: "tshirt-product-id",
      quantity: 1,
      custom_inputs: {
        front: "Happy Birthday Dad!",
        back: "From your favorite child",
      },
    },
  },
});

Note that products with different custom_inputs values will be added as separate line items, even if they are the same product.

Re-ordering from Previous Orders

You can help customers re-add items from previous orders to their current cart:

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

const cartId = getCartId();
const orderId = "order-12345";

// Re-order items from a previous order
const response = await manageCarts({
  path: {
    cartID: cartId,
  },
  body: {
    data: {
      type: "reorder",
      id: orderId,
    },
  },
});

Cart Limitations and Best Practices

• A cart can contain a maximum of 100 unique items
• Items include products, custom items, tax items, and promotions
• For custom items, include a unique SKU to properly identify them
• The cart currency is set when the first item is added to the cart
• All products must have prices in the same currency as the cart

Response Handling

The response contains the updated cart items:

// Example response handling in a React component
const [isAddingToCart, setIsAddingToCart] = useState(false);
const [successMessage, setSuccessMessage] = useState("");
const [cartCount, setCartCount] = useState(0);

const handleAddToCart = async (productId) => {
  setIsAddingToCart(true);

  try {
    const result = await addToCart(productId);

    // Show success message
    setSuccessMessage(`Item added to your cart`);

    // Update cart count
    setCartCount(result.data.relationships.items.data.length);

    // Optionally refetch cart data to update UI
    await fetchCart();
  } catch (error) {
    setErrorMessage(error.message || "Failed to add item to cart");
  } finally {
    setIsAddingToCart(false);
  }
};

Common Implementation Patterns

• "Add to Cart" Button: The most common implementation that adds a single item to the cart

<button
  onClick={() => product.id && handleAddToCart(product.id)}
  disabled={isAddingToCart}
  className="bg-blue-500 hover:bg-blue-600 text-white py-2 px-3 rounded"
>
  {isAddingToCart ? "Adding..." : "Add to Cart"}
</button>

• Quick-add functionality: Add items directly from product listings
• Add with options: Include product variants or customizations when adding to cart

Error Handling

• Out-of-stock scenarios: Check inventory before adding or handle API errors
• Invalid product IDs: Ensure the product exists before attempting to add
• Quantity restriction violations: Handle minimum and maximum quantity constraints

tip

For more detailed information about adding different types of items to a cart, see the Elastic Path API documentation.

tip

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