Application proxies - front end development

An application proxy is a feature that fetches and displays data on a Shopify shop page from an outside location that you, the developer, specify. For app developers, this means that the content on these proxy pages can be dynamic; capable of being updated as much as you feel necessary. App developers can use application proxies to display image galleries, statistics and custom forms, just to name a few examples.

Application proxies do not have to be set up before installation to start working. Application proxies added to an app after it is installed will update its existing install-base.

As a bonus, through the application proxy, it is possible to have Shopify render Liquid responses from the Proxy URL. Liquid is Shopify's customization engine and rendering a Liquid response displays your proxy page as if it were a part of the shop's theme.

Add a proxy to your app

  1. From your Partners dashboard, click Apps.
  2. Click on your app's name.
  3. Click Edit app settings.
  4. In the App proxy section, select a Sub path prefix from the drop-down menu and enter your sub path URL:

    App proxy settings
    These settings determine which HTTP requests to Shopify are proxied to the Proxy URL that you enter in the next step.

  5. Set the Proxy URL to the URL of your proxy server.


    Shopify does not recognize localhost or as the proxy URL and will return an error.

  6. Click Save changes.


Consider the following app proxy configuration:

  • Sub path prefix: apps
  • URL: my-app-proxy
  • Proxy URL:

In this example, will be forwarded to, the Proxy URL.

What the store owner sees

After a store owner installs an app with a proxy, they have the ability to change the sub-path. The sub-path is where the application proxy will be accessed from a store owner's own shop (Apps > Manage Apps). Store owners may choose to change the sub-path so that the URL in the location bar makes the proxy page appear like it is being hosted in their store instead of externally. Ultimately, the sub-path is purely for shop aesthetics and will not affect the actual location of the proxy URL (edited sub-paths will still be forwarded to the proxy URL).

Issue a proxy request

When Shopify receives an HTTP request for a proxied path, it will forward that request to the specified Proxy URL. For example, when the following HTTP request is sent from the client user agent:

GET /apps/awesome_reviews/extra/path/components?extra=1&extra=2 HTTP/1.1
  Cookie: csrftoken=01234456789abcdef0123456789abcde;

Shopify will forward the request using the specified Proxy URL.

Given that the Proxy URL is set to, the client's IP address is and the applications shared secret is hush, the forwarded request will look like the following:

GET/proxy/extra/path/components?extra=1&extra=2& HTTP/1.1

Cookies are not supported for the application proxy, since the application is accessed through the shop's domain. Shopify will strip the Cookie header from the request and Set-Cookie from the response.

The forwarded request adds the following parameters:

  • shop: The domain for the shop.
  • path_prefix: The proxy sub-path prefix at which the shop was accessed. In this case, it's/apps/awesome_reviews, which was replaced in the forwarded request URL with the proxy application's Proxy URL.
  • timestamp: The time in seconds since midnight of January 1, 1970 UTC.
  • signature: Verifies that the request was sent by Shopify. A hexadecimal encoded SHA-256 HMAC of the other parameters, split on the "&" character, unencoded, sorted, concatenated and using the applications Shared Secret as the HMAC key.

Security: Calculate a digital signature

Just like our webhooks, we sign all our proxy requests.

In Ruby, the algorithm for calculating the signature looks like this using the ruby-hmac gem:

require 'rubygems'
require 'openssl'
require 'rack/utils'

# Use request.query_string in rails
query_string = "extra=1&extra=2&"

query_hash = Rack::Utils.parse_query(query_string)
# => {
#   "extra" => ["1", "2"],
#   "shop" => "",
#   "path_prefix" => "/apps/awesome_reviews",
#   "timestamp" => "1317327555",
#   "signature" => "a9718877bea71c2484f91608a7eaea1532bdf71f5c56825065fa4ccabe549ef3",
# }

# Remove and save the "signature" entry
signature = query_hash.delete("signature")

sorted_params = query_hash.collect{ |k, v| "#{k}=#{Array(v).join(',')}" }.sort.join
# => "extra=1,2path_prefix=/apps/awesome_reviewsshop=shop-name.myshopify.comtimestamp=1317327555"

calculated_signature = OpenSSL::HMAC.hexdigest('sha256'), SHARED_SECRET, sorted_params)
raise 'Invalid signature' if signature != calculated_signature

The request method and request body will be forwarded, so content from form submission and AJAX requests can be used in the proxy application. In this case, the URL will still contain the query parameters added by the proxy (i.e. shop, path_prefix, timestamp, and signature) even when the body also contains URL encoded parameters.

Proxy response

If the HTTP response from the Proxy URL has Content-Type: application/liquid set in its headers, Shopify will evaluate and render any Liquid code in the request's body in the context of the shop using the shop's theme. When used the right way, it can automatically make your app look like it belongs as part of the shop without any manual intervention.

Otherwise, the response will be returned directly to the client. 30* redirects will be followed in case you need that sort of thing.