The Sync API allows for a higher degree of integration with Shopify merchants than is possible through the Sell Anything API, but requires that you have a relationship in place between yourself and the merchant. Merchants must install the Rye app to their Shopify store using an installation link that you provide them.

Once the app has been installed and set up, all of the products sold by that merchant will be immediately available to you via the Sync API and you will also have access to Sync API-specific features such as commissions.

Tutorial

Installation links for stores can be generated programmatically using GraphQL. The ShopifyApp.installationLink field is what you are interested in querying:

query GenerateInstallationLink {
  shopifyApp {
    installationLink(
      storeCanonicalDomain: "my-shopify-partner.com"
    ) {
      canonicalDomain
      url
    }
  }
}

Note that the installation link generated by this operation is specific to the store that you provide. If you have multiple merchants you want to sell products from, then you will need to generate a unique installation link for each of them by varying the storeCanonicalDomain input argument.

The returned url field contains the installation link. You should share this with your merchant, and ask them to open it in their browser.

{
  "data": {
    "shopifyApp": {
      "installationLink": {
        "canonicalDomain": "my-shopify-partner.myshopify.com",
        "url": "https://my-shopify-partner.myshopify.com/admin/oauth/authorize?..."
      }
    }
  }
}

Step 2: Merchant installs the app

When the merchant opens the installation link in their browser, they will be taken to the Shopify app installation page. They will be asked to authorize the app to access their store. Once they have done this, the app will be installed and they will be redirected back to the app.

You can send this guide to your merchants to help guide them through the Shopify app installation process.

Step 3: Verify installation status

Once the merchant has finished setting up the app using your installation link, Rye will fire a SHOPIFY_APP_CONNECTED webhook. Receipt of this event is enough to confirm that the merchant has successfully installed the app and that you can now access their products via the Sync API. If the merchant ever uninstalls the app or revokes your access to their store then a corresponding SHOPIFY_APP_DISCONNECTED webhook will be fired.

If you have not configured webhooks then you can also poll the installation status via the integratedShopifyStore query. This query will return null if you do not have access to the store through the Sync API, and this can be used to determine whether the merchant has installed the app.

Step 4: Query product data

After you have onboarded your merchants, you can retrieve information using the following API operations:

  • productByID

    Used to retrieve information about a specific product.

  • productsByDomainV2

    Used to retrieve all products from the specified store domain.

In the case of the Sync API, productsByDomainV2 will be the most appropriate API operation to use as you likely won’t know any product IDs upfront. The following query would return product catalog data from Gymshark’s USA store, assuming you have access to it:

productsByDomainV2
query GetGymsharkProducts {
  productsByDomainV2(
    input: {
      domain: "gymsharkusa.myshopify.com"
    }
    pagination: {
      # Note: Pagination is limited to 100 items per page
      limit: 100
      offset: 0
    }
  ) {
    id
    title
  }
}

Note that it is possible for productsByDomainV2 to return product data that you do not have access to through the Sync API. This happens in cases where another developer has added the products to our Sell Anything API, but you do not have access to the Sync API for that store. This is why it is important to verify installation status before attempting to access product data.

Congratulations!

At this point you have successfully onboarded some or all of your partner merchants to Rye, and have access to their product catalog through our APIs. From here most developers will want to sync this data to their own system, but you could also go ahead and jump straight to placing an order if you prefer.