How to

Show shipping/payment options

Retrieve available shipping and payment options and display them to users

Overview

Learn how to fetch available shipping and payment options for a checkout session and update the selection based on customer preferences. This guide covers dynamic option retrieval and handling customer choices.

Prerequisites

Merchant API key
Existing cart with items

Goal

Retrieve all available shipping options
Retrieve all available payment options

Architecture at a glance

Get options → Display to user

Step-by-step

Get available shipping and payment options

Create a checkout session to retrieve all available options based on the cart contents and user data (if user is logged in).

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

Request example

mutation createOrUpdateCheckout(
  $cartId: String!
  $checkout: CheckoutInputType
  $channelId: String
  $languageId: String
  $marketId: String
) {
  createOrUpdateCheckout(
    cartId: $cartId
    checkout: $checkout
    channelId: $channelId
    languageId: $languageId
    marketId: $marketId
  ) {
    shippingOptions {
      id
      displayName
      feeIncVat
      isSelected
      logo
    }
    paymentOptions {
      id
      displayName
      feeIncVat
      isSelected
      logo
      paymentType
    }
  }
}

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

{
  "cartId": "{CART_ID}",
  "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 createOrUpdateCheckout($cartId: String!, $checkout: CheckoutInputType, $channelId: String, $languageId: String, $marketId: String) { createOrUpdateCheckout(cartId: $cartId, checkout: $checkout, channelId: $channelId, languageId: $languageId, marketId: $marketId) { shippingOptions { id displayName feeIncVat isSelected logo } paymentOptions { id displayName feeIncVat isSelected logo paymentType } } }","variables":{"cartId":"{CART_ID}","channelId":"{CHANNEL_ID}","languageId":"{LANGUAGE_ID}","marketId":"{MARKET_ID}"}}'

Response example

200 OK

response.json

{
  "data": {
    "createOrUpdateCheckout": {
      "cart": {
        "id": "{CART_ID}",
        "summary": {
          "total": {
            "regularPriceIncVat": 348.00
          }
        }
      },
      "shippingOptions": [
        {
          "id": 1,
          "displayName": "Standard",
          "feeIncVat": 59,
          "isSelected": true,
          "logo": null
        },
        {
          "id": 7,
          "displayName": "Store pickup",
          "feeIncVat": 0,
          "isSelected": false,
          "logo": "store"
        }
      ],
      "paymentOptions": [
        {
          "id": 23,
          "displayName": "Klarna Checkout",
          "feeIncVat": 0,
          "isSelected": false,
          "logo": "payment-klarna",
          "checkoutType": "EXTERNAL"
        },
        {
          "id": 27,
          "displayName": "Geins Pay",
          "feeIncVat": 0,
          "isSelected": false,
          "logo": "payment-geins",
          "checkoutType": "GEINS_PAY"
        },
        {
          "id": 18,
          "displayName": "Manual Invoice",
          "feeIncVat": 0,
          "isSelected": false,
          "logo": "payment-invoice",
          "paymentType": "STANDARD"
        }
      ]
    }
  }
}

Display options to the customer

Use the returned data to display shipping and payment options in your checkout UI.

Options

Payment types

Different payment types require different handling:

STANDARD: Manual payment method for manual invoicing. Use with placeOrder mutation to complete checkout.
EXTERNAL: Payment providers like Klarna or Svea that use iframes. Returns HTML in paymentData after selection for embedding the payment widget.
GEINS_PAY: Geins Pay method, needs an address provided to return the paymentData HTML for embedding the payment widget.

Multi-market support

All mutations 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 about using multi-market support.

Authenticated access

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

Handle cases where options become unavailable (e.g., if shipping address changes)
When changing payment methods, be prepared to handle different payment flows

Some payment and shipping providers require specific front end implementations to work correctly, refer to their documentation for details.

Clone a cart

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

Filter products

Filter products using facets with includeMode and filterMode. Learn to build faceted navigation with parameters, categories, and brands using Geins Merchant API