Shopify Hydrogen Integration Guide

This guide covers how to integrate the STRABL checkout flow into a Shopify Hydrogen/Oxygen storefront. It focuses on the data pipeline: reading cart data, building the payload, calling the STRABL API, and redirecting the customer.

This guide is intended for developers and technical personnel only. It assumes familiarity with software development concepts and system integration.

Where to Place This Code

All the functions and logic in this guide (buildStrablPayload, createStrablCheckout) should live directly in your checkout route file, the same file that renders your checkout button and handles the checkout flow.

In a typical Hydrogen storefront, this would be:

app/routes/checkout.jsx

Everything stays in file: Helper functions at the top, the loader for server-side cart data, and the default export component with your checkout button.

What if I have a cart drawer?

If your storefront has a cart drawer/sidebar (a slide-out cart), the code will go in the cart drawer component file. The cart drawer can access the cart data using useRouteLoaderData('root') and call createStrablCheckout from there:

Architecture Overview

The integration runs when a customer clicks the checkout button:

Read the Shopify cart data from your Hydrogen loader

Build the STRABL checkout payload from the cart data

POST to STRABL's create cart API

Receive a cartId (token) and redirect to the STRABL checkout URL

Click → Build STRABL Payload → Create Cart session → redirect

Prerequisites

A STRABL Platform UUID, obtained from your Strabl dashboard. Store this in your Hydrogen environment variables (e.g., .env):

STRABL_PLATFORM_UUID="123456-1234-1234-XXXX-XXXXXXXXXXXX"

Step-by-Step Implementation

Step 1: Pass `platformUuid` from your loader

In your checkout route loader, read the env var and pass cart + platform UUID to the component:

// app/routes/checkout.jsx
export async function loader({context}) {
  const {cart, env} = context;
  const cartData = await cart.get();
  if (!cartData || cartData.totalQuantity === 0) {
    throw new Response('Cart is empty', {status: 404});
  }
  return {
    cart: cartData,
    storeDomain: env.PUBLIC_STORE_DOMAIN || '',
    platformUuid: env.STRABL_PLATFORM_UUID || '',
  };
}

Step 2: Build the Strabl checkout payload from Hydrogen cart data

The Hydrogen Storefront API returns cart data through cart.get() in your loader. Map it to the format Strabl expects:

Step 3: Create the checkout session and redirect

Step 4: Wire it to your checkout button

export default function Checkout() {
  const {cart, storeDomain, platformUuid} = useLoaderData();
  const [isLoading, setIsLoading] = useState(false);
  const [error, setError] = useState(null);
  const handleStrablCheckout = async () => {
    setIsLoading(true);
    setError(null);
    try {
      const checkoutUrl = await createStrablCheckout({
        cart,
        platformUuid,
        storeDomain,
      });
      window.location.href = checkoutUrl;
    } catch (err) {
      setError(err.message || 'Failed to create checkout session');
      setIsLoading(false);
    }
  };
  return (
    <div>
      {error && <p style={{color: 'red'}}>{error}</p>}
      <button onClick={handleStrablCheckout} disabled={isLoading}>
        {isLoading ? 'Processing...' : 'Checkout with Strabl'}
      </button>
    </div>
  );
}

Sample Complete File

Sample Code

Payload Reference

Full Request Body

{
  "cartObject": {
    "store": {
      "name": "My Shopify Store",
      "url": "https://my-store.com",
      "logo": "https://my-store.com/images/logo.png",
      "platformUuid": "4038344c-..."
    },
    "cart": {
      "total": 299.99,
      "subTotal": 249.99,
      "currency": "AED",     
      "items": [
        {
          "title": "Classic T-Shirt",
          "description": "",
          "price": 149.99,
          "sku": "TSH-BLK-M",
          "productId": "12345678",
          "variantId": "456789887",
          "url": "/products/classic-t-shirt",
          "image": "https://cdn.shopify.com/...",
          "quantity": 2,
          "variantOptions": ["Size: M", "Color: Black"]
        }
      ],
      "extra": {
        "shopifyCheckoutId": "xyz-1234..."
      }
    }
  }
}

Response (success)

{
  "data": {
    "cartId": "e7a2b3c4-d5f6-..."
  }
}

Shopify Hydrogen Integration Guide

Where to Place This Code#

What if I have a cart drawer?#

Architecture Overview#

Prerequisites#

Step-by-Step Implementation#

Step 1: Pass platformUuid from your loader#

Step 2: Build the Strabl checkout payload from Hydrogen cart data#

Step 3: Create the checkout session and redirect#

Step 4: Wire it to your checkout button#

Sample Complete File#

Payload Reference#

Full Request Body#

Response (success)#

Where to Place This Code

What if I have a cart drawer?

Architecture Overview

Prerequisites

Step-by-Step Implementation

Step 1: Pass `platformUuid` from your loader

Step 2: Build the Strabl checkout payload from Hydrogen cart data

Step 3: Create the checkout session and redirect

Step 4: Wire it to your checkout button

Sample Complete File

Payload Reference

Full Request Body

Response (success)