Skip to content
Tutorials Center
My learning

Topics

Lesson 33 of 55 ยท App Extensions

App Proxy and Storefront Pages

Serve pages and data from your own server under a store's domain with an app proxy: URL mapping, the signature check, Liquid responses and when to choose it.

Most of what you have built so far lives inside the admin or inside Shopify-hosted surfaces such as checkout. Sometimes you need something different: a page on the storefront itself, under the shop's own domain, that is produced by your server. Think of a "Track my order" page, a wishlist page, a store locator, or a small JSON endpoint that theme JavaScript can call. An app proxy does exactly this. A visitor opens https://example-shop.com/apps/tracker/lookup, Shopify forwards the request to your server, and your answer appears as part of the store.

In this lesson you will learn how the proxy URL is mapped, which extra parameters Shopify adds to every forwarded request, how to verify the signature so that nobody can call your endpoint while pretending to be Shopify, and how to return either JSON or a Liquid page that is rendered inside the shop's theme. You will also learn when an app proxy is the wrong tool. For the surrounding picture, see App Architecture at a Glance and App Extensions Overview.

What runs here. A real proxy needs a store and a public server, so all real configuration and route code below is read-only. The live examples are Node.js stand-ins: they implement the documented signing recipe with a fake secret and a simulated request, which is the part you can reason about and test anywhere. Parameter names and rules are summarized from memory of the platform; confirm them against the current app proxy reference before shipping.

How the URL is mapped

You declare the proxy in your app configuration. The three pieces of the storefront URL are a prefix, a subpath and the rest of the path:

TOML
# shopify.app.toml (read-only excerpt)
[app_proxy]
url = "https://my-app.example.com/proxy"
subpath = "tracker"
prefix = "apps"

The prefix is chosen from a short list that Shopify allows (apps is the most common one), the subpath is your own name, and url is where your server listens. With the settings above:

Visitor requests Your server receives
https://example-shop.com/apps/tracker GET https://my-app.example.com/proxy
https://example-shop.com/apps/tracker/lookup?order=1001 GET https://my-app.example.com/proxy/lookup?order=1001&shop=...&timestamp=...&signature=...

The visitor never sees your server's domain. Shopify receives the storefront request, adds some parameters, and calls you. Because the call comes from Shopify's servers and not from the visitor's browser, your endpoint does not need CORS headers for pages the visitor opens directly; if theme JavaScript calls /apps/tracker/... on the same domain, that is a same-origin call too.

sequenceDiagram
    participant V as Visitor browser
    participant S as Shopify storefront
    participant A as Your server
    V->>S: GET /apps/tracker/lookup?order=1001
    S->>S: Add shop, timestamp and sign the query
    S->>A: GET /proxy/lookup?order=1001&shop=...&signature=...
    A->>A: Verify signature
    A-->>S: 200 + Liquid or JSON
    S-->>V: Page inside the theme, or the JSON

The visitor only ever talks to the shop's domain; Shopify signs the forwarded request.

The parameters Shopify adds

Every forwarded request carries extra query parameters. The ones you will use:

Parameter Meaning
shop The shop's myshopify.com domain that received the request
timestamp Unix time (seconds) when Shopify forwarded the request
signature The proof that Shopify sent it (explained below)
path_prefix The storefront prefix and subpath, such as /apps/tracker
logged_in_customer_id The id of the logged-in customer, or empty when nobody is logged in

The last one is valuable: if a customer is logged in on the storefront, Shopify tells you who they are, and because the whole request is signed you can trust it. It is the usual way to build "my account" style pages without building your own login. Treat it as an id only; to read the customer's data you still call the Admin API with your own access token (see Orders, Customers and Protected Data).

Verifying the signature

A proxy URL on your server is public. Anyone can call https://my-app.example.com/proxy/lookup?logged_in_customer_id=12345 directly and claim to be customer 12345. The signature parameter is how you tell Shopify's calls from forgeries.

The recipe, in words:

  1. Take all query parameters except signature.
  2. Turn each into name=value. If a parameter has several values, join them with a comma.
  3. Sort those strings alphabetically.
  4. Concatenate them with no separator (not &).
  5. Compute an HMAC-SHA256 of that string with your app's client secret, and encode it as hexadecimal.
  6. Compare with the signature in constant time.

Two details trip people up. First, the proxy signature is hex, while webhooks use base64 (see Verifying Webhook Signatures). Second, there is no & between the pairs, so a value can in theory blur into the next name; this is a property of the scheme, not something you can change, and one more reason to treat every parameter as untrusted input after the check.

The signature has no built-in expiry, but the timestamp is signed with everything else. A sensible server also rejects requests whose timestamp is far in the past, so a captured URL cannot be replayed for days.

Node.js Sign and verify a proxy request

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Run it and look at case 2: changing a single value (here the customer id) breaks the signature, so the forged customer id is rejected. Case 5 shows a repeated parameter joined with a comma before signing.

Responding with JSON or Liquid

Your server decides the response type with the Content-Type header.

  • JSON (or any non-Liquid body). Return application/json and Shopify passes it to the visitor as it is. This is how theme JavaScript calls your server: fetch('/apps/tracker/lookup?order=1001').
  • Liquid. Return Content-Type: application/liquid and a body written in Liquid, and Shopify renders it inside the shop's theme layout: header, footer, fonts and cart all match the store. Because Liquid is rendered by Shopify, your template can use store objects such as shop, customer and cart, and filters such as money.

A read-only sketch of a Node route that does both (check your own framework for the equivalent):

JavaScript
// app/routes/proxy.lookup.js  (read-only sketch)
export async function loader({ request }) {
  const url = new URL(request.url);
  if (!isValidProxySignature(url.searchParams, process.env.SHOPIFY_API_SECRET)) {
    return new Response("Unauthorized", { status: 401 });
  }

  const order = url.searchParams.get("order");
  const status = await findTrackingStatus(url.searchParams.get("shop"), order);

  if (url.searchParams.get("format") === "json") {
    return Response.json({ order, status });
  }

  const page = `
    <h1>Order {{ "${order}" | escape }}</h1>
    <p>Status: {{ "${status}" | escape }}</p>
    {% if customer %}<p>Hi {{ customer.first_name }}.</p>{% endif %}
  `;
  return new Response(page, { headers: { "Content-Type": "application/liquid" } });
}

Notice the | escape filter. If you paste visitor-controlled text such as the order query parameter into HTML without escaping it, you have created a cross-site scripting hole on the merchant's own domain. Escape in Liquid or on your server before the text reaches the page. The Liquid you return is also not a place for secrets: whatever your template prints is visible to every visitor who can load the page.

Node.js A tiny proxy route: verify, then choose a response

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The hostile order value is printed as harmless text because it was escaped. The forged call never reaches the lookup logic.

When to use an app proxy

An app proxy is the right answer when the thing you need is a page or endpoint on the storefront domain that needs your server: customer-specific pages, dynamic data that does not belong in metafields, a form that posts to your backend, or a public API for your own theme blocks. It also keeps your server's domain out of the browser's address bar and avoids cross-origin setup.

It is the wrong answer in several common cases:

  • Content merchants place in the theme editor. Use a theme app extension with an app block; it is faster and merchant-friendly.
  • Data that changes rarely. Store it in metafields and let the theme read it with Liquid; there is no round trip to your server at all.
  • High-traffic product pages. Every proxy request is a request to your server. A slow or failing proxy slows or breaks the page, so cache what you can and set tight timeouts.
  • Anything inside checkout. Checkout has its own extension model; see Checkout UI Extensions.

Finally, remember that merchants must be able to remove your proxy cleanly: if the app is uninstalled, the URL stops working, so links you added to a theme should degrade gracefully.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. A visitor opens /apps/tracker/lookup on a store whose proxy URL is https://my-app.example.com/proxy. Where does Shopify send the request?

    Shopify receives the storefront request, maps the path under the configured proxy URL and adds shop, timestamp, signature and other parameters before calling your server.
  2. 2. How is the app proxy signature calculated?

    Remove the signature parameter, sort the name=value pairs, concatenate them without any separator, and compute a hex HMAC-SHA256 with the app's client secret. Webhooks, in contrast, use base64 over the raw body.
  3. 3. Which response header makes Shopify render your body inside the store's theme?

    A body returned as application/liquid is rendered by Shopify as Liquid within the theme layout. JSON and other types are passed through unchanged.
  4. 4. You show the order query parameter on the page. What must you do?

    The signature proves the request came through Shopify, not that the visitor's values are harmless. Unescaped output is a cross-site scripting risk on the merchant's own domain.

Summary

  • An app proxy maps a storefront path such as /apps/tracker/... to a URL on your server; the visitor never sees your domain.
  • Shopify adds shop, timestamp, signature, path_prefix and logged_in_customer_id to each forwarded request.
  • Verify the hex HMAC-SHA256 over the sorted, concatenated name=value pairs with your client secret, compare in constant time and reject stale timestamps.
  • Return JSON for scripts or application/liquid for pages rendered inside the theme; always escape visitor-controlled text.
  • Prefer theme app extensions for merchant-placed content and metafields for static data; keep proxy endpoints fast and cached.

Next, move from the storefront to the checkout engine: Shopify Functions Overview.