Set up Recharge authentication for Shopify Customer Account UI extensions

This guide explains how to authenticate logged-in Shopify customers in a Customer Account UI extension and create a Recharge customer session so developers can build custom customer portals powered by Recharge.

📘
Platform

Shopify Checkout Integration

Migrated Shopify Checkout Integration

Overview

Shopify Customer Account UI extensions cannot call the Recharge Storefront API directly. Instead, you must:

Validate the Shopify customer session token on your backend
Map the Shopify customer to a Recharge customer
Create a Recharge customer session
Return the session token to the UI extension

This ensures the request is authenticated, authorized, and scoped to the logged-in customer.

Step 1: Create Recharge API Tokens

In the Recharge Merchant Portal, navigate to:

Tools & Apps → API Tokens
Create two tokens:

Token type	Required scopes	Used for
Storefront token	Select required scopes	Create customer session in Recharge
Admin token	`write_session`, `read_customer`	Look up customer by Shopify ID

Step 2: Create the backend endpoint

Shopify Customer Account UI extensions cannot directly call the Recharge Storefront API. All Recharge authentication must be handled server-side.

On your backend, create an endpoint that:

Accepts a Shopify Customer Account session token
Validates the token server-side
Generates a Recharge customer session
Returns the session token to the caller

This endpoint is called by your Shopify Customer Account UI extension and acts as a secure bridge between Shopify authentication and the Recharge Storefront API.

Step 3: Call the backend endpoint from the UI extension

From your Shopify Customer Account UI extension, send the Shopify session token to your backend endpoint.

await fetch("https://YOUR-SERVER.COM/create_recharge_customer_session", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    token: SHOPIFY_SESSION_TOKEN, // JWT provided by Shopify session-token API
  }),
});

Step 4: Implement the backend endpoint

Implement the backend endpoint that your Shopify Customer Account UI extension calls to create a Recharge customer session.

This endpoint is responsible for:

Validating the incoming Shopify session token (JWT)
Extracting the Shopify customer ID from the token
Looking up the corresponding customer in Recharge
Creating a Recharge customer session using the Storefront API
Returning the customer session token to the caller

🚧
Important

The Shopify session token is a JWT and must be verified server-side.

The Recharge customer session returned by this endpoint is not a JWT. Treat it as an opaque, customer-scoped token.

The example below shows a simple JavaScript implementation:

Example implementation (JavaScript)

// Helper: Validate incoming Shopify session token properly
function validateShopifyToken(token) {
  // Follow Shopify verification steps:
  // https://shopify.dev/docs/apps/build/authentication-authorization/session-tokens/set-up-session-tokens#verify-the-session-tokens-signature
}

// Helper: Parse Shopify `gid://shopify/Customer/<id>` string format
function parseGid(gid) {
  return gid.split("/").pop(); // returns <customerId>
}

export async function createRechargeCustomerSession(req, res) {
  try {
    const sessionToken = req?.body?.token;

    // 1. Verify the incoming Shopify session token
    if (!validateShopifyToken(sessionToken)) {
      return res.status(401).json({ error: "Invalid Shopify session token" });
    }

    // 2. Decode Shopify token to extract the customer ID
    const tokenInfo = readSessionToken(sessionToken); // implement readSessionToken
    const shopifyCustomerId = parseGid(tokenInfo.sub);

    console.log("Mapped Shopify Customer ID:", shopifyCustomerId);

    // 3. Look up the matching Recharge customer
    const customerResponse = await fetch(
      `https://api.rechargeapps.com/customers?external_customer_id=${shopifyCustomerId}`,
      {
        headers: {
          "X-Recharge-Version": "2021-11",
          "X-Recharge-Access-Token": process.env.RECHARGE_ADMIN_TOKEN,
        },
      }
    );

    const customerData = await customerResponse.json();
    const customer = customerData?.customers?.[0];

    if (!customer) {
      return res.status(404).json({
        error:
          "Customer not found in Recharge — no subscriptions for this account yet.",
      });
    }

    // 4. Create a Recharge customer session
    const sessionResponse = await fetch(
      `https://api.rechargeapps.com/customers/${customer.id}/sessions`,
      {
        method: "POST",
        headers: {
          "X-Recharge-Version": "2021-11",
          "Content-Type": "application/json",
          "X-Recharge-Access-Token": process.env.RECHARGE_ADMIN_TOKEN,
          "x-recharge-storefront-access-token":
            process.env.RECHARGE_STOREFRONT_TOKEN,
        },
        body: JSON.stringify({}),
      }
    );

    const result = await sessionResponse.json();
    const customerSession = result.customer_session;

    // Example response:
    // { api_token: "...", customer_id: 12345 }

    return res.json({ customerSession });
  } catch (err) {
    console.error(err);
    res.status(500).json({
      error: "Failed to create Recharge session",
      message: err.message,
    });
  }
}