How to

Use external shipping frame

Use an external shipping provider frame (e.g., nShift) to let customers select delivery options using Geins Merchant API

Overview

Learn how to implement a checkout flow using an external shipping provider frame such as nShift. This allows customers to select pickup points, delivery times, and other shipping options directly within an embedded widget.

Prerequisites

Merchant API key
Existing cart with items
External shipping provider configured (e.g., nShift)
Customer's zip/postal code

Goal

Create a checkout session with basic customer information
Initialize the external shipping frame with zip code
Display the shipping widget and capture customer selections
Update checkout with selected shipping options

Architecture at a glance

Create checkout → Initialize shipping frame with zip → Display widget → Capture selections → Update checkout

Step-by-step

Create checkout session

Start by creating a checkout session.

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
  ) {
    cart {
      id
      summary {
        total {
          regularPriceIncVat
        }
      }
    }
    shippingData
  }
}

{
  "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) { cart { id summary { total { regularPriceIncVat } } } shippingData }","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": 299.00
          }
        }
      },
      "shippingData": null
    }
  }
}

Supply zip code to initialize shipping frame

Update the checkout with the customer's zip/postal code to initialize the external shipping frame.

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
  ) {
    shippingData
  }
}

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

{
  "cartId": "{CART_ID}",
  "checkout": {
    "billingAddress": {
      "zip": "{ZIP_CODE}",
    }
  },
  "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) { shippingData }","variables":{"cartId":"{CART_ID}","checkout":{"billingAddress":{"zip":"{ZIP_CODE}"}},"channelId":"{CHANNEL_ID}","languageId":"{LANGUAGE_ID}","marketId":"{MARKET_ID}"}}'

Response example

200 OK

response.json

{
  "data": {
    "createOrUpdateCheckout": {
      "shippingData": "<div id=\"nshift-checkout\"><!-- NShift iframe HTML --></div><script>/* NShift script */</script>"
    }
  }
}

Display the external shipping widget

Embed the external shipping provider's widget in your checkout page. The exact implementation depends on your shipping provider.

The external shipping widget is provided by your shipping provider. Refer to their documentation for specific initialization parameters and callback handling.

Update checkout with selected shipping data

After the customer selects a delivery option in the widget, update the checkout with the selection details, this is different depending on your shipping provider.

Request variables example

query-variables.json

{
  "cartId": "{CART_ID}",
  "checkout": {
    "billingAddress": {
      "zip": "{ZIP_CODE}",
    },
    "externalShippingId": "12345",
    "pickupPoint": "12345_67899",
    "message": "Delivery details: Pickup Point"
  },
  "channelId": "{CHANNEL_ID}",
  "languageId": "{LANGUAGE_ID}",
  "marketId": "{MARKET_ID}"
}

Options

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

Ensure the zip/postal code format matches what the shipping provider expects
The external shipping widget must be properly configured in your Geins backend

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

Use external payment frame

Complete checkout using an external payment provider frame with Geins Merchant API

Use multi-market support

Learn how to use graphql arguments to target specific sales channels, markets, and languages in Geins Merchant API