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 resolver is set up to work with either a canonical or storefront domain:

query CreateInstallationLink {
  shopifyApp {
    installationLink(storeCanonicalDomain: "my-cool-store.com") {
      canonicalDomain
      url
    }
  }
}

​
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:

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.

1

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.

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

Receive canonical domain

Note that the canonicalDomain field contains a different domain from the one provided to requestShopifyProductByURL.

{
  "data": {
    "requestShopifyProductByURL": {
      "canonicalDomain": "gymsharkusa.myshopify.com",
      "productId": "6805424341194"
    }
  }
}
3

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:

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

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.