Skip to main content

Build a Custom Landing Page with Wuilt Cart APIs

This guide shows how to build your own marketing or campaign landing page outside Wuilt, while still using the Wuilt cart and checkout.

You will:

  • Ask the merchant for the product URL on their storefront (from which you can derive the product handle).
  • Generate a sessionId on your side and send it in the sessionid header.
  • Use GetProductDetails to fetch the product and its variants by handle.
  • Add items to a cart using SampleAPIs.
  • Optionally apply promo codes.
  • Read cart details for UI (price/summary).
  • Redirect to the unified Wuilt checkout.

At the end of this guide you’ll find an embedded example landing page inside this document using an <iframe>.

1. Prerequisites​

Before you start, you should have:

  • A Wuilt store (domain like pharmacy.wuiltstore.com).
  • Your GraphQL endpoint: https://graphql.wuilt.com.
  • An API key configured in the docs UI.
  • The following SampleAPIs available:
    • AddToCart
    • ReplaceCartItems
    • GetCart
    • ApplyPromoCode
    • CheckoutCart (Redirect-only page)

You should also be comfortable making HTTPS requests from your landing page (e.g. using fetch in the browser or a backend proxy).

2. Generate and use sessionId​

Your landing page is responsible for generating and persisting a session identifier.

  1. When the visitor first performs a cart operation (for example clicks “Add to Cart” or “Buy Now”), generate a UUIDv4 and prefix it:
    • Example: Session_3f6a0f1d-9c4a-4f3e-8f4b-1a2b3c4d5e6f.
  2. Store it in localStorage so you reuse the same value across all cart calls (and even across different landing pages) until you intentionally regenerate it.
  3. Send it as an HTTP header with every cart-related GraphQL request:
sessionid: Session_3f6a0f1d-9c4a-4f3e-8f4b-1a2b3c4d5e6f

The backend uses this header to resolve which cart belongs to your visitor.

3. Fetch product details by handle (GetProductDetails)​

Before you let users add to cart, fetch the product and its variants for the landing page using the GetProductDetails SampleAPI (which uses storeProductByHandle).

  • Operation: GetProductDetails.
  • Input: storeId + handle (derived from the product URL) and optional locale.

Example:

  • URL: https://pharmacy.wuiltstore.com/en/products/example-product
  • Handle: example-product

Use the returned product and variants.nodes to:

  • Render title, descriptions, images.
  • Show variant options (size, color, etc.).
  • Let the shopper choose a specific variantId and quantity.

4. Add items to cart from the landing page​

Use the AddToCart SampleAPI to add a variant when the user clicks your CTA (e.g. “Add to Cart” or “Get Offer”).

  • Operation: AddToCart (see SampleAPIs → AddToCart).
  • Input: SimpleItemInput with variantId and quantity.
  • Header: sessionid as described above.

Typical flow in your frontend:

  1. User clicks Add to Cart.
  2. Your code sends a GraphQL mutation AddToCart.
  3. You optionally refresh the cart UI using GetCart.

5. Implement "Buy Now" behaviour (ReplaceCartItems)​

If your landing page should behave like Buy Now (cart contains only the chosen product), use ReplaceCartItems instead of AddToCart:

  • Operation: ReplaceCartItems.
  • Input: same SimpleItemInput shape.
  • Effect: cart is cleared and replaced with the provided item.

Use this when you want:

  • A single-product funnel.
  • The cart to always mirror the current landing page offer.

6. Apply promo codes​

If your landing page includes a promo code input, use ApplyPromoCode:

  • Operation: ApplyPromoCode.
  • Input: cartId + code (e.g. SUMMER-2025).
  • Header: same sessionid.

Recommended sequence:

  1. Add or replace cart items.
  2. Call GetCart to get cart.id.
  3. Call ApplyPromoCode with that cartId and the user-entered code.
  4. Show any errors (cartErrors) to the customer.
  5. Show updated totals using the returned cart or GetCart.

7. Update or remove items (UpdateCartItems)​

To let users change quantities or remove items directly from the landing page, use the UpdateCartItems SampleAPI (which wraps the updateSimpleItem mutation):

  • Operation: UpdateCartItems.
  • Input: SimpleItemInput with variantId and quantity.

Behavior:

  • quantity > 0 → update the item quantity.
  • quantity = 0 → remove the item from the cart.

Typical UI patterns:

  • Quantity input or +/- buttons that call UpdateCartItems with the new quantity.
  • A "Remove" button that calls UpdateCartItems with quantity: 0.

8. Read cart details (GetCart)​

Use GetCart to render cart information on the landing page with storefront-ready data only when you already have a sessionId stored. If no sessionId exists yet, do not call GetCart; instead, render a placeholder empty cart UI.

  • Operation: GetCart.
  • Input: id: Cart_....

What you typically display from items and receipt:

  • Product title, short description, and a primary image.
  • Variant information (e.g. size, color, SKU) when relevant.
  • Quantity and line price / total price per item.
  • Cart subtotal, discounts (including automatic discounts), shipping, tax, and total.

You can:

  • Call GetCart after every cart mutation (AddToCart, ReplaceCartItems, UpdateCartItems, ApplyPromoCode) as long as a sessionId exists.
  • Or poll GetCart periodically to keep UI in sync (for more complex flows), again only when a sessionId is present, to avoid creating unnecessary empty carts.

9. Redirect to checkout​

When the customer is ready to pay, use CheckoutCart Redirect (docs only) to build the URL and redirect.

You need:

  • cartId – from GetCart.
  • store_domain – e.g. pharmacy.wuiltstore.com.
  • locale – e.g. en.
  • storeHandle – for Wuilt Pay, from your existing checkout URL.

7.1 Without Wuilt Pay​

https://{store_domain}/{locale}/checkout/{cartId}

Example:

https://pharmacy.wuiltstore.com/en/checkout/Cart_d8f8ce2f-681e-4554-93b7-230e0b34a151

8.2 With Wuilt Pay​

https://pay.wuiltstore.com/{locale}/store/{storeHandle}/cart/{cartId}

Example:

https://pay.wuiltstore.com/en/store/groceries-test-store/cart/Cart_b9a8ee66-5bf0-4cc0-9f78-7e8ac2403b87

In your landing page JavaScript:

window.location.href = checkoutUrl;

10. End-to-end flow summary​

  1. Fetch product: GetProductDetails by handle (from product URL).
  2. Initialize session: generate and store sessionId on first cart interaction.
  3. Add/replace items: AddToCart or ReplaceCartItems.
  4. Read cart: GetCart to get cart.id and totals.
  5. Apply promo (optional): ApplyPromoCode.
  6. Update/remove items: UpdateCartItems.
  7. Redirect: Build the appropriate checkout URL and redirect the browser.

This pattern lets you design any front-end experience you want, while Wuilt handles the cart, shipping, and checkout logic behind the scenes.