Sales Channel SDK getting started

Note

This SDK is not yet publicly available, but you can apply to become eligible.

In this guide, we walk through reading product listings and staying in sync with any changes to these listings using webhooks. Product listings are the lists of products that merchants have published to your channel, and retrieving these listings is a common sales channel scenario.

Throughout this guide, we cover authenticating to the API using OAuth, requesting the required access scopes, registering for channel-specific webhooks, and, finally, making calls to the API to read product listings and create a checkout.

Setting up for a sales channel

To create your sales channel:

  1. Navigate to your partner Dashboard and click Create a new app, from the Apps section.
  2. On the Create a new app page make sure that the Embedded App SDK is enabled.
  3. Provide the App URLs corresponding to your app’s authorization and Redirection URL routes.
  4. Click Create App and take note of your API key and secret.

Note

When developing your Embedded App, you will need to follow best practices

Authorization with OAuth

For a deep dive with OAuth, check out the Oauth docs or the advanced public app tutorial that walks through the entire OAuth handshake. In this guide we cover OAuth in the context of OAuth scopes and webhook subscriptions for sales channels.

A sales channel enables merchants to list and sell their products on your marketplace or platform. Sales channels are public Shopify apps and use OAuth to operate on behalf of the merchant. As part of the Oauth flow, Shopify obtains the user’s authorization, and issues an access token which your sales channel can use to interact with the API.

Requesting channel specific scopes

When a merchant installs your sales channel app it must redirect them to Shopify's auth grant screen to request the required scopes. The route should use the following format:

https://{shop}.myshopify.com/admin/oauth/authorize?client_id={api_key}&scope={scopes}&redirect_uri={redirect_uri}&state={nonce}&grant_options[]={option}

where shop is the domain of the merchant shop, api_key is your app's api key, scopes represents the scopes requested, and redirect_uri is where the app will redirect after install.

As part of this route, your app can request the following Oauth access scopes: read_product_listings, read_collection_listings. You can also request write_checkouts if your app will be using the Checkout API.

For more detailed information, see the OAuth documentation.

Obtaining the access token

After the merchant authorizes, your app receives the required authorization code and HMAC parameters. The authorization code is exchanged for an access token, and the HMAC parameters are used to validate the redirect is coming from Shopify. To learn about HMAC verification, see the OAuth docs.

Note

It should be noted that when doing OAuth with embedded apps, your initial OAuth request redirect must escape the iframe. For more information see the Embedded App SDK Getting Started.

To get an access token, send a POST request to https://<shop>/admin/oauth/access_token: Ensure that it includes shop, client_id, client_secret, and code, where client_id is your API key, and client_secret is your app's shared secret.

After receiving the access token, you can use it to instantiate a session with Shopify.

Interacting with product listings

Using the access token, you can begin to make calls to the Shopify API.

To retrieve product listings, send a GET request to the admin/applications/{app_id}/product_listings.json endpoint.

Example Request:

curl -X GET -H "X-Shopify-Access-Token: 35df6efd065b8ce72dca9493e5ec34c5" "https://{shop}.myshopify.com/admin/applications/{id}/product_listings.json"

Where {shop} is the domain of the Shopify store, and {id} is the automatically generated unique identifier of your app provided by Shopify.

Example Response:

In response to a properly formatted GET request, the API will return the product listings formatted as JSON, as per the following example:


{
  "product_listings": [
    {
      "product_id": 8624796102,
      "created_at": "2016-12-15T11:29:20-05:00",
      "updated_at": "2016-12-15T11:29:20-05:00",
      "body_html": "",
      "handle": "test",
      "product_type": "",
      "title": "Test",
      "vendor": "dev-ex",
      "available": true,
      "tags": "",
      "published_at": "2016-12-15T11:29:20-05:00",
      "images": [],
      "options": [
        {
          "id": 10378526214,
          "name": "Title",
          "product_id": 8624796102,
          "position": 1
        }
      ],
      "variants": [
        {
          "id": 29900866950,
          "title": "Default Title",
          "option_values": [
            {
              "option_id": 10378526214,
              "name": "Title",
              "value": "Default Title"
            }
          ],
          "price": "19.99",
          "formatted_price": "$19.99",
          "compare_at_price": null,
          "grams": 0,
          "requires_shipping": true,
          "sku": "",
          "barcode": "",
          "taxable": true,
          "position": 1,
          "available": true,
          "inventory_policy": "deny",
          "inventory_quantity": -1,
          "inventory_management": null,
          "fulfillment_service": "manual",
          "weight": 0,
          "weight_unit": "kg",
          "image_id": null,
          "created_at": "2016-09-22T19:44:01-04:00",
          "updated_at": "2016-11-24T23:03:39-05:00"
        }
      ]
    }
  ]
}

Registering for webhooks

After you have read the merchant’s products that are intended for your channel, you'll want to stay in sync with these product listings over time. One approach is to register a set of sales channel specific webhooks that will notify you of changes to the product catalog.

To register for the webhook:

  1. Specify the subscription topic, such as product_listings/add.
  2. Provide the webhook URL, where Shopify will send you webhook notifications.
  3. Indicate the preferred response format (eg. JSON).

Example:

HTTP:

POST /admin/webhooks.json HTTP/1.1
Host: channelsrule.myshopify.com
X-Shopify-Access-Token: 085abas8bd90325c3f81s8e9c88befc0
Content-Type: application/json

{
    "webhook": {
        "topic": "product_listings/add",
        "address": "https://yourchannelapp.com/webhooks",
        "format": "json",
    }
}

Processing webhooks

After you register the product_listings/add endpoint, your application will receive POST requests to the specified address when product listings are added. Your sales channel must be able to correctly process these POST requests and extract the data from the body of the request. The body of the request will contain the information about the product listing.

Note that HMAC verification for webhooks is different from OAuth verification/validation. For more information, see Using Webhooks.

Next steps

Learn how to bill for your sales channel