Skip to main content

​
Overview

Henry’s Universal Cart endpoints lets you manage a universal shopping cart for your users. All you need to provide is a product link and variant information for items to be added to cart. It’s up to you whether you want to use your own product catalog or rely on Henry’s Product Discovery APIs to fetch product details.

​
Required headers

  • x-api-key: Your Henry Shopping API key (sandbox or production)
  • x-user-id: Stable identifier for the shopper. Use the same value everywhere you read or mutate the cart.
1

Add or update items

Use POST /cart/items to append new products. The response returns added_products, updated_products, and a cart_summary with totals.
const addToCart = await fetch("https://api.sandbox.henrylabs.ai/v0/cart/items", {
  method: "POST",
  headers: {
    "x-api-key": process.env.HENRY_API_KEY,
    "x-user-id": "user_123",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    productsDetails: [
      {
        productId: "P01145AC2",
        name: "Cloud 6 Versa",
        price: "149.00",
        quantity: 1,
        productLink: "https://merchant.com/products/cloud-6-versa",
        productImageLink: "https://merchant.com/images/cloud-6-versa.png",
        metadata: { size: "9", color: "Black" }
      }
    ],
    checkVariantAvailability: true
  })
});

const cartPayload = await addToCart.json();
console.log(cartPayload.data.cart_summary);
Setting checkVariantAvailability to true instructs Henry to trigger the experimental variant validation service. Any pending checks appear under data.variant_checks with a variantCheckRequestId.
2

Remove individual products

When a shopper deletes one line item, call DELETE /cart/items/{productId}. The productId value must match the ID you originally supplied or the ID returned from the initial POST /cart/items call.
await fetch("https://api.sandbox.henrylabs.ai/v0/cart/items/P01145AC2", {
  method: "DELETE",
  headers: {
    "x-api-key": process.env.HENRY_API_KEY,
    "x-user-id": "user_123"
  }
});
3

Clear the cart

To reset the cart entirely, use DELETE /cart/items. The response confirms the cart is empty, which is useful when a user logs out. The cart is automatically cleared when the user completes a checkout.
await fetch("https://api.sandbox.henrylabs.ai/v0/cart/items", {
  method: "DELETE",
  headers: {
    "x-api-key": process.env.HENRY_API_KEY,
    "x-user-id": "user_123"
  }
});
Reuse the same x-user-id in downstream checkout calls so Henry can hydrate the cart automatically when you initiate a hosted session or build a headless flow.

​
Troubleshooting

  • 400 Bad Request – validate price formatting (string in the schema) and ensure the quantity is greater than zero.
  • 404 Cart already empty – only occurs when clearing an empty cart; you can safely ignore it in idempotent flows.
  • Variant check requests require polling via GET /products/variant-check/{id} for a definitive in-stock answer.
Continue to Cart Checkout once you are ready to convert carts into orders.