How to

Check out headless cart

Complete the checkout process for a headless cart using Geins Merchant API

Overview

Learn how to create a cart, add items to it, and then complete the checkout process using Geins Merchant API.

Prerequisites

  • Merchant API key
  • Known SKU to add to the cart
  • Available shipping ID
  • Available payment ID
Read the display shipping/payment options guide to learn how to retrieve available shipping and payment options for your cart.

Goal

  • Create a new cart
  • Add products to the cart
  • Complete the checkout process and place an order

Architecture at a glance

  • Create cart → Add items to cart → Place order → Get order confirmation

Step-by-step

Create a new cart

Start by creating a new cart using the getCart query. When no cart ID is provided, a new cart will be created automatically.

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

Request example

query getCart(
  $id: String
  $channelId: String
  $languageId: String
  $marketId: String
) {
  getCart(
    id: $id
    channelId: $channelId
    languageId: $languageId
    marketId: $marketId
  ) {
    id
    items {
      id
      skuId
      quantity
      unitPrice {
        regularPriceIncVat
      }
      totalPrice {
        regularPriceIncVat
      }
    }
    summary {
      total {
        regularPriceIncVat
      }
    }
  }
}

Response example

200 OK
response.json
{
  "data": {
    "getCart": {
      "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "items": [],
      "summary": {
        "total": { ... },
      }
    }
  }
}

Add items to the cart

Now add products to your cart using the addToCart mutation. You'll need the cart ID from step 1 and a valid SKU ID (as an integer).

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
      unitPrice {
        regularPriceIncVat
      }
      totalPrice {
        regularPriceIncVat
      }
    }
    summary {
      total {
        regularPriceIncVat
      }
    }
  }
}

Response example

200 OK
response.json
{
  "data": {
    "addToCart": {
      "id": "{CART_ID}",
      "items": [
        {
          "id": "xxx",
          "skuId": {SKU_ID},
          "quantity": 2,
          "unitPrice": {
            "regularPriceIncVat": 20.00,
          },
          "totalPrice": {
            "regularPriceIncVat": 40.00,
          }
        }
      ],
      "summary": {
        "total": { ... },
      }
    }
  }
}

Place the order

Complete the checkout process by placing the order using the placeOrder mutation. You'll need the cart ID and checkout information including shipping IDs.

Request example

mutation placeOrder(
  $cartId: String!
  $checkout: CheckoutInputType!
  $channelId: String
  $languageId: String
  $marketId: String
) {
  placeOrder(
    cartId: $cartId
    checkout: $checkout
    channelId: $channelId
    languageId: $languageId
    marketId: $marketId
  ) {
    orderId
    publicId
  }
}
The channelId, languageId, and marketId arguments are optional and can be left out to use default values.

Response example

200 OK
response.json
{
  "data": {
    "placeOrder": {
      "orderId": "order-id-12345",
      "publicId": "ORD-2025-001234",
    }
  }
}

Options

Multi-market support

All mutations and queries support optional parameters for multi-market functionality:

  • channelId: Target specific sales channels
  • languageId: Set content language
  • marketId: Target specific markets
Read more about channelId, languageId, and marketId in the "how to"-article about using multi-market support.

Authenticated access

While authentication is not required for these mutations, including a JWT bearer token in the Authorization header can provide personalized results based on the authenticated user's context, for example personalized pricing and pre-filled user information.

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

  • Ensure the SKU ID exists and is available
  • Verify that the shipping ID is a valid integer for your merchant setup
  • Check that the cart has items before attempting to place an order
  • Note that addToCart accepts a single item, not an array - call it multiple times for multiple items
Related

Activate promo code on cartAdd custom data to cartAdd product to cartCheck out headless cartClone a cartShow shipping/payment optionsGet cartUse external payment frameUse external shipping frameUse multi-market supportGetCartAddToCartPlaceOrder

Change user password

Change user passwords securely using Geins Auth Service's signature-based flow

Clone a cart

Duplicate an existing cart for a seamless shopping experience using Geins Merchant API