> Agent-readable docs index: /llms.txt. Download /docs.zip to grep all markdown files locally.

---
title: "Shopify Store Domains"
description: "The Rye API uses the canonical domain to identify unique Shopify stores. This article explains the difference between the storefront domain and the canonical domain, and how to use them in the API."
---

When working with Shopify stores, there are two kinds of store domain that you need to be aware of:

* **Storefront domain**: This is the domain on which the store is hosted. Customers purchasing directly from the merchant would use this domain to browse and use the storefront. Example: `my-cool-store.com`.
* **Canonical domain**: A unique domain used by Shopify to identify the store. Customers accessing the canonical domain directly will be redirected to the storefront domain by Shopify. The canonical domain is *always* a `myshopify.com` subdomain. Example: `e8548f-63.myshopify.com`.

Rye uses the **canonical domain** to identify unique Shopify stores as the storefront domain can be changed by the merchant at any time. It is important to know that the canonical domain may not be the same as the storefront domain.

Certain operations in the Rye API can take *either* the canonical domain or the storefront domain, and determine the correct canonical domain under the hood automatically. In cases like this, the API will return the resolved canonical domain as part of the response so you can use it in subsequent requests.

For example, the [`ShopifyApp.installationLink`](/api-reference/shopifyapp) resolver is set up to work with either a canonical or storefront domain:

<Tabs items={["Request", "Response"]}>
  <Tab title="Request">
    ```graphql
    query CreateInstallationLink {
      shopifyApp {
        installationLink(storeCanonicalDomain: "my-cool-store.com") {
          canonicalDomain
          url
        }
      }
    }
    ```
  </Tab>

  <Tab title="Response">
    ```json
    {
      "data": {
        "shopifyApp": {
          "installationLink": {
            "canonicalDomain": "e8548f-63.myshopify.com",
            "url": "https://e8548f-63.myshopify.com/admin/oauth/authorize?..."
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

## Developer guidelines

### When to use each domain

Most Rye API methods are designed to work specifically with the canonical domain. This means that in general you should prefer use of the canonical domain over the storefront domain.

Merchants have a lot of flexibility with respect to how they configure their domains, which means it isn't always obvious what the canonical domain should be given a storefront domain. The correct canonical domain for `gymshark.com`, for instance, is *not* `gymshark.myshopify.com` like you might assume! The correct canonical domain is `gymsharkusa.myshopify.com`; `gymshark.myshopify.com` is the canonical domain for their UK store.

Because it can be difficult to accurately determine the canonical domain upfront, the following operations accept either one of the two domains and will attempt to resolve the correct canonical domain for you:

* [`ShopifyApp.installationLink`](/api-reference/shopifyappinstallationlink)
* [`integratedShopifyStore`](/api-reference/integratedShopifyStore)
* [`requestShopifyProductByURL`](/api-reference/requestshopifyproductbyurl)
* [`requestStoreByURL`](/api-reference/requeststorebyurl)

All of these operations return a `canonicalDomain` field on their payload which you can save and use for subsequent requests.

### Example: Tracking a product

In this example, we'll walk through the process of requesting a product by URL and saving the canonical domain for future use.

<Steps>
  <Step title="Request a Shopify product">
    Here the publicly-accessible URL of the product is provided to `requestShopifyProductByURL`. The Sell Anything API will resolve the correct canonical domain while processing this requestAnimationFrame.

    ```graphql
    mutation RequestProduct {
      requestShopifyProductByURL(input: {
        url: "https://gymshark.com/products/gymshark-everyday-seamless-sports-bra-black-ss24"
      }) {
        canonicalDomain
        productId
      }
    }
    ```
  </Step>

  <Step title="Receive canonical domain">
    Note that the `canonicalDomain` field contains a different domain from the one provided to `requestShopifyProductByURL`.

    ```json
    {
      "data": {
        "requestShopifyProductByURL": {
          "canonicalDomain": "gymsharkusa.myshopify.com",
          "productId": "6805424341194"
        }
      }
    }
    ```
  </Step>

  <Step title="Save the canonical domain">
    At this point, you'll want to save the canonical domain somewhere so you can reference it later. The exact details of how you do this will depend on your tech stack; here, we're using a SQL database:

    ```sql
    insert into "product" ("id", "canonical_domain", "request_url")
    values (
      '6805424341194',
      'gymsharkusa.myshopify.com',
      'https://gymshark.com/products/gymshark-everyday-seamless-sports-bra-black-ss24'
    )
    ```
  </Step>

  <Step title="Use the canonical domain">
    Now that you have the correct canonical domain saved, you can look it up and use it for future API calls.
  </Step>
</Steps>


---

*Powered by [holocron.so](https://holocron.so)*