How to

Add product to cart

Add products to an existing cart using Geins Merchant API

Prerequisites

Merchant API key
Existing cart ID
Valid product SKU ID

Learn how to get a cart ID by following the Get cart guide.

Architecture at a glance

Use addToCart mutation → Product added to cart → Cart updated with new totals

APIs used

Merchant API: https://merchantapi.geins.io/graphql

Step-by-step

Add a product to the cart

Use the addToCart mutation to add a product to your cart. You'll need the cart ID and a valid SKU ID (as an integer):

Try it out in the GraphQL Playground using the query, headers and variables below.

Request example

mutation addToCart(
  $id: String!
  $item: CartItemInputType!
  $channelId: String
  $languageId: String
  $marketId: String
) {
  addToCart(
    id: $id
    item: $item
    channelId: $channelId
    languageId: $languageId
    marketId: $marketId
  ) {
    id
    items {
      id
      skuId
      quantity
      product {
        name
      }
      unitPrice {
        regularPriceIncVat
      }
      totalPrice {
        regularPriceIncVat
      }
    }
    summary {
      total {
        regularPriceIncVat
      }
    }
  }
}

{
  "Accept": "application/json",
  "X-ApiKey": "{MERCHANT_API_KEY}"
}

{
  "id": "{CART_ID}",
  "item": {
    "skuId": {SKU_ID},
    "quantity": 2
  },
  "channelId": "{CHANNEL_ID}",
  "languageId": "{LANGUAGE_ID}",
  "marketId": "{MARKET_ID}"
}

curl -X POST https://merchantapi.geins.io/graphql \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-ApiKey: {MERCHANT_API_KEY}" \
  -d '{"query":"mutation addToCart($id: String!, $item: CartItemInputType!, $channelId: String, $languageId: String, $marketId: String) { addToCart(id: $id, item: $item, channelId: $channelId, languageId: $languageId, marketId: $marketId) { id items { id skuId quantity product { name } unitPrice { regularPriceIncVat } totalPrice { regularPriceIncVat } } summary { total { regularPriceIncVat } } } }","variables":{"id":"{CART_ID}","item":{"skuId":{SKU_ID},"quantity":2},"channelId":"{CHANNEL_ID}","languageId":"{LANGUAGE_ID}","marketId":"{MARKET_ID}"}}'

The channelId, languageId, and marketId arguments are optional and can be left out to use default values.

Response example

200 OK

response.json

{
  "data": {
    "addToCart": {
      "id": "{CART_ID}",
      "items": [
        {
          "id": "item-id-1",
          "skuId": {SKU_ID},
          "quantity": 2,
          "name": "Premium Wireless Headphones",
          "unitPrice": {
            "regularPriceIncVat": 99.00
          },
          "totalPrice": {
            "regularPriceIncVat": 198.00
          }
        }
      ],
      "summary": {
        "total": {
          "regularPriceIncVat": 198.00
        }
      }
    }
  }
}

Adding multiple products

To add multiple different products to the cart, call the addToCart mutation multiple times.

The addToCart mutation accepts a single item, not an array. Call it multiple times to add multiple different products.

Quantity behavior

When adding a product that already exists in the cart:

The quantity will be added to the existing quantity
Example: Cart has 2 units of SKU 12345, adding 3 more results in 5 total units

Multi-market support

The mutation supports optional parameters for multi-market configurations:

Read more about channelId, languageId, and marketId in the multi-market support guide.

While authentication is not required for this mutation, including a JWT bearer token in the Authorization header can provide personalized results based on the authenticated user's context, for example personalized pricing.

To include authentication, add the JWT bearer token to your request headers:

"Authorization": "Bearer {JWT_TOKEN}"

Read more about obtaining and using JWT tokens in the guide about the authentication flow.

Common pitfalls

Invalid SKU ID - ensure the product exists and is available for purchase
Invalid cart ID - the cart may have expired or been deleted
Out of stock items - check product availability before adding to cart

Add custom data to cart

Learn how to add custom data to carts using Geins Merchant API

Build product listing

Build a product listing page (PLP) with facets and pagination using Geins Merchant API.