--- title: About app proxies and dynamic data description: App proxies allow the display of dynamic data within storefronts. source_url: html: https://shopify.dev/docs/apps/build/online-store/app-proxies md: https://shopify.dev/docs/apps/build/online-store/app-proxies.md --- ExpandOn this page * [How it works](https://shopify.dev/docs/apps/build/online-store/app-proxies#how-it-works) * [Getting started](https://shopify.dev/docs/apps/build/online-store/app-proxies#getting-started) * [App proxy properties](https://shopify.dev/docs/apps/build/online-store/app-proxies#app-proxy-properties) * [User customization](https://shopify.dev/docs/apps/build/online-store/app-proxies#user-customization) * [Liquid response](https://shopify.dev/docs/apps/build/online-store/app-proxies#liquid-response) * [Disallowed headers](https://shopify.dev/docs/apps/build/online-store/app-proxies#disallowed-headers) * [Next steps](https://shopify.dev/docs/apps/build/online-store/app-proxies#next-steps) # About app proxies and dynamic data App proxies take requests to Shopify URLs, and proxy them to your app. This allows you to fetch and display data on a storefront from an external source. A Shopify app can have only one proxy route configured. Any paths under this root URL will proxy to your app. *** ## How it works Shopify will proxy a storefront URL to your app based on your [app proxy configuration](https://shopify.dev/docs/apps/build/cli-for-apps/app-configuration#app_proxy): ## shopify.app.toml ```toml [app_proxy] url = "/my-app-proxy" prefix = "apps" subpath = "my-custom-path" ``` In this example: * `https:///apps/my-custom-path` will proxy to `https:///my-app-proxy`. * `https:///apps/my-custom-path/child-route` will proxy to `https:///my-app-proxy/child-route`. Configuring an app proxy requires the `write_app_proxy` [access scope](docs/api/usage/access-scopes#authenticated-access-scopes). Note You can also configure an app proxy in the Dev Dashboard by navigating to **Apps** > **{your app}** > **Versions** > **Create a version** > **App proxy**. However, Shopify recommends [file-based configuration](https://shopify.dev/docs/apps/build/cli-for-apps/app-configuration) which can be source controlled and deployed via Shopify CLI. *** ## Getting started Use the following steps to create an app proxy using the Shopify Remix template. ### Requirements * You're a [user with app development permissions](https://shopify.dev/docs/apps/build/dev-dashboard/user-permissions) and have created a [development store](https://shopify.dev/docs/api/development-stores#create-a-development-store-to-test-your-app). - You're using the latest version of [Shopify CLI](https://shopify.dev/docs/api/shopify-cli). - You're using the latest version of [Chrome](https://www.google.com/chrome/) or [Firefox](https://www.mozilla.org/). * You've [created an app that uses the Remix template](https://shopify.dev/docs/apps/build/scaffold-app). ### Step 1: Create the proxy route 1. If it's not already running, start the `shopify app dev` command. ## Terminal ```terminal shopify app dev ``` 2. Create a route in your app to [handle proxy requests](https://shopify.dev/docs/apps/build/online-store/display-dynamic-data#how-it-works) at `app/routes/my-app-proxy.jsx`: ## app/routes/my-app-proxy.jsx ```jsx import { authenticate } from "../shopify.server"; import { useLoaderData } from "@remix-run/react"; export const loader = async ({ request }) => { // Use the authentication API from the Remix template await authenticate.public.appProxy(request); // Read URL parameters added by Shopify when proxying const url = new URL(request.url); return { shop: url.searchParams.get("shop"), loggedInCustomerId: url.searchParams.get("logged_in_customer_id"), }; }; export default function MyAppProxy() { const { shop, loggedInCustomerId } = useLoaderData(); return
{`Hello world from ${loggedInCustomerId || "not-logged-in"} on ${shop}`}
; } ``` ### Step 2: Update configuration 1. In `shopify.app.toml` in the root of your app, add the `write_app_proxy` [access scope](https://shopify.dev/docs/apps/build/authentication-authorization/app-installation/manage-access-scopes). ## shopify.app.toml ```toml [access_scopes] scopes = "write_app_proxy" ``` 2. In the same app configuration file, add your [app proxy configuration](#app-proxy-properties): ## shopify.app.toml ```toml [app_proxy] url = "/my-app-proxy" prefix = "apps" subpath = "my-custom-path" ``` ### Step 3: Test the app proxy 1. The `shopify app dev` command will automatically update the app on your development store. 2. Test the proxy by opening the proxied path on your storefront. In this example that's `https:///apps/my-custom-path`. Note Because [users can customize](#user-customization) the `prefix` and `subpath` values, they are immutable on a store after installation. Once you set these values in your `shopify.app.toml`, to change them during development you must use your dev store admin. You can also uninstall and reinstall the app to reinitialize the proxied path. *** ## App proxy properties All properties are required. | Property | Description | | - | - | | `url` | This can either be:- A relative URL for your proxy endpoint. Shopify will prepend your app URL during `shopify app dev` and `shopify app deploy.` - An absolute URL for your proxy endpoint. If [enabled in your app config](https://shopify.dev/docs/apps/build/cli-for-apps/app-configuration#build), Shopify will update the host name with your app URL during `shopify app dev`. | | `prefix` | The first part of the proxy URL on the shop. It must match an [allowed value](https://shopify.dev/docs/apps/build/cli-for-apps/app-configuration#app_proxy) (`a`, `apps`, `community`, or `tools`). | | `subpath` | The second part of the proxy URL on the shop. It may contain letters, numbers, underscores, and hyphens up to 30 characters. The value may not be `admin`, `services`, `password`, or `login`. | *** ## User customization Users can change the subpath or prefix of app proxies in Shopify Admin by navigating to **Settings** > **Apps and sales channels** > **{your app}** > **App proxy** > **Customize URL**. While users can change this information to get a friendlier URL that fits their store's information architecture, these changes don't affect the root destination URL for your proxy endpoint. Because these values are configurable by users, changes to the `subpath` and `prefix` in your app will only apply to new app installations. *** ## Liquid response App proxies support [Liquid](https://shopify.dev/docs/api/liquid), Shopify's template language. An app proxy response that contains Liquid will be rendered with store data into HTML like it was part of the store's theme. If the HTTP response from the proxy URL has `Content-Type: application/liquid` set in its headers, then Shopify renders any Liquid code in the request body in the context of the shop using the shop's theme. Otherwise, the response is returned directly to the client. Also, any [30x redirects](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#3xx_Redirection) are followed. *** ## Disallowed headers Due to security concerns, the following headers are stripped from app proxy responses: * `Accept-Patch` * `Accept-Ranges` * `Connection` * `Cookie` * `Date` * `Delta-Base` * `IM` * `P3P` * `Pragma` * `Preference-Applied` * `Proxy-Authenticate` * `Public-Key-Pins` * `Server` * `Service-Worker-Allowed` * `Set-Cookie` * `Trailer` * `Tk` * `Warning` * `X-Powered-By` *** ## Next steps * If you are not using the Remix template, you can [build your own authentication for app proxies](https://shopify.dev/docs/apps/build/online-store/app-proxies/authenticate-app-proxies). * Explore the [app configuration reference](https://shopify.dev/docs/apps/build/cli-for-apps/app-configuration#app_proxy) for app proxies. *** * [How it works](https://shopify.dev/docs/apps/build/online-store/app-proxies#how-it-works) * [Getting started](https://shopify.dev/docs/apps/build/online-store/app-proxies#getting-started) * [App proxy properties](https://shopify.dev/docs/apps/build/online-store/app-proxies#app-proxy-properties) * [User customization](https://shopify.dev/docs/apps/build/online-store/app-proxies#user-customization) * [Liquid response](https://shopify.dev/docs/apps/build/online-store/app-proxies#liquid-response) * [Disallowed headers](https://shopify.dev/docs/apps/build/online-store/app-proxies#disallowed-headers) * [Next steps](https://shopify.dev/docs/apps/build/online-store/app-proxies#next-steps)