Abstract

In the quest to reduce friction in the purchasing journey, Cart Permalinks have emerged as a powerful, low-code tool. These specialized URLs allow developers and marketers to construct pre-filled carts programmatically, bypassing the browsing phase entirely. This chapter explores the mechanics of constructing these links, injecting complex attributes and properties via Base64 encoding, and integrating them into Hydrogen storefronts for headless conversion flows.

The Mechanics of the Permalink

At its simplest, a Cart Permalink is a URL that instructs Shopify to create a cart with specific items. The syntax follows the pattern: https://{shop}.myshopify.com/cart/{variant_id}:{quantity},{variant_id}:{quantity}.

Example:

To add 1 unit of Variant A and 2 units of Variant B:

https://store.com/cart/12345:1,67890:2

This mechanism is invaluable for email marketing, retargeting ads, and “Buy Now” buttons on third-party blogs. It effectively turns any digital touchpoint into a direct checkout entry point.

Advanced Parameterization: Beyond Basic Items

The true power of permalinks lies in the additional data that can be passed via query parameters.

1. Discount Injection:
   Appending ?discount=SUMMERSALE applies a discount code automatically. This is critical for influencer campaigns where the user should not have to manually copy-paste a code.

• Complex Chain: …/cart/123:1?discount=CODE1,CODE2 (Stacking discounts if allowed).

1. Checkout Pre-Filling:
   To further reduce friction, known customer data can be injected into the URL.
   ?checkout[email][email protected]&checkout[shipping_address][city]=NewYork.

• Strategy: A CRM system sending a cart abandonment email can generate a unique link for each user, pre-filling their email so they land on the payment step immediately.

1. Attribution and Tracking:
   The attributes parameter allows developers to tag orders with source data that is invisible to the user but accessible in the Admin API.
   ?attributes[source]=instagram_bio&attributes[campaign_id]=jan_2025.

Technical Implementation in Hydrogen

In a Hydrogen (headless) environment, the standard Shopify permalink logic requires manual handling if the goal is to retain the user on the headless domain before redirecting. The following loader demonstrates how to parse a permalink-style URL and create a server-side cart using the Storefront API.

// app/routes/($locale).cart.$lines.tsx
import { type LoaderFunctionArgs, redirect } from '@shopify/remix-oxygen';

export async function loader({ request, context, params }: LoaderFunctionArgs) {
  const { cart } = context;
  const { lines } = params; // extracted string: "123:1,456:2"

  // 1. Parse the line items
  const linesMap = lines?.split(',').map((line) => {
    const [variantId, quantity] = line.split(':');
    return {
      merchandiseId: `gid://shopify/ProductVariant/${variantId}`,
      quantity: parseInt(quantity, 10),
    };
  });

  // 2. Extract discount from query string
  const url = new URL(request.url);
  const discount = url.searchParams.get('discount');
  const discountCodes = discount? [discount] :;

  // 3. Create Cart via Storefront API mutation
  const result = await cart.create({
    lines: linesMap,
    discountCodes,
  });

  // 4. Persist cart session cookie
  const headers = cart.setCartId(result.cart.id);

  // 5. Redirect to the checkout URL returned by Shopify
  return redirect(result.cart.checkoutUrl, { headers });
}

This code allows a headless store to support the same permalink marketing strategies as a Liquid store, maintaining feature parity.

The Base64 Property Hack

A frequent requirement is selling personalized items (e.g., “Engraved Watch”) via a permalink. Since standard parameters cannot easily handle complex object structures, the solution is Base64 encoding.

Process:

1. Create a JSON object: {“engraving”: “Happy Birthday”, “font”: “Arial”}.
2. Base64 encode the string.
3. Append as the properties parameter: ?properties=eyJlbmdyYXZpbmci….

This technique allows for highly complex product configurations to be passed through a simple URL, bridging the gap between social commerce and complex product customization.