Skip to main content

Add To Cart

AddToCart Mutation

This mutation adds a simple product variant to the customer cart. The cart is resolved by the sessionid header that you send with the request.

Use Cases​

  • Landing page add-to-cart: Add a product from a custom landing page built outside Wuilt.
  • Multi-step funnels: Add items while the user progresses through a funnel.
  • Campaign pages: Attach a specific variant/offer to a session-scoped cart.

Headers​

The client must send a session identifier header, generated on your side (UUID v4):

{
  "sessionid": "Session_3f6a0f1d-9c4a-4f3e-8f4b-1a2b3c4d5e6f"
}

This value is used by the backend to resolve which cart to modify.

Input Parameters​

  • $storeId: ID! – The store in which the cart lives.
  • $item: SimpleItemInput!
    • variantId: ID! – The product variant to add.
    • quantity: Int! – Quantity to add.
    • (Optional) itemId: ID – Used when updating an existing line; not needed for new lines.

Response Structure​

Returns a Cart object with:

  • id – Cart identifier (Cart_...).
  • sessionId – The session this cart belongs to.
  • status / cartStep – Current state of the cart.
  • items – Line items; for simple items:
    • id – Cart item id.
    • quantity – Item quantity.
    • price – Unit price (Money).
    • variant – Selected variant details.
  • receipt – Monetary breakdown:
    • subtotal, discount, shipping, tax, total (Money).

Example Variables​

{
  "storeId": "Store_cm84j35iy02m001i89iiu2cts",
  "item": {
    "variantId": "ProductVariant_example_001",
    "quantity": 1
  }
}

Implementation Notes​

  • Always reuse the same sessionid header for all cart actions in a single customer journey.
  • You can call AddToCart multiple times to accumulate items in the same cart.
  • Combine with GetCart to render cart summaries or mini-carts on custom pages.

GraphQL Endpoint​

https://graphql.wuilt.com

Operation: AddToCart​

Try It Out​

Query​

mutation AddToCart($storeId: ID!, $item: SimpleItemInput!) {
customerActions(storeId: $storeId) {
  cart {
    addSimpleItem(item: $item) {
      id
      sessionId
      cartStep
      status
      items {
        ... on CartSimpleItem {
          id
          quantity
          price {
            amount
            currencyCode
          }
          product {
            id
            title
            shortDescription
            descriptionHtml
            handle
            images {
              id
              src
              altText
              width
              height
            }
          }
          variant {
            id
            sku
            price {
              amount
              currencyCode
            }
            compareAtPrice {
              amount
              currencyCode
            }
            image {
              id
              src
              altText
              width
              height
            }
          }
        }
      }
      receipt {
        subtotal {
          amount
          currencyCode
        }
        discount {
          amount
          currencyCode
        }
        shipping {
          amount
          currencyCode
        }
        tax {
          amount
          currencyCode
        }
        total {
          amount
          currencyCode
        }
      }
    }
  }
}
}

Query Variables

1
2
3
4
5
6
7

Note: Make sure to change the storeId with your store ID. For guidance on how to get your store ID, reference the Store ID guide.

Authentication​

To use this query, you will need an API key. Click the "API Key" button in the navigation bar to enter your credentials.