Getting started with the Sales Channel SDK

This guide describes how to set up a sales channel app using the Sales Channel SDK. It covers 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.

Create a sales channel app

Sales channel apps require an app name and URL, as well as app extension configuration information. If you want to process credit card payments, then you'll also need to request payment processing when you create the sales channel app.

Create an app in your Partner Dashboard

To create an app:

  1. From your Partner Dashboard, click Apps.
  2. On the Apps page, click Create app.
  3. Enter an App name and App URL, and place a checkmark next to "I have read and agree to the Partner Program Agreement".
  4. Click Get API credentials.
  5. Verify your App URL and Whitelisted redirection URL, and take note of your API key and secret.

Enable App Extensions

Before an app can be a sales channel, you need to configure its App Extension configuration.

To configure your sales channel App Extensions:

  1. From your app's overview page, click Extensions to access the App Extensions screen.
  2. Next to Embed In Shopify admin click Enable. This enables the Embedded App SDK, allowing your sales channel app to embed directly inside the Shopify admin.
  3. In the Sales channel section, click Turn app into sales channel.

Note

This is a one-way process, which can't be reversed. If you no longer want your app to be a sales channel, then you will need to re-create it.

  1. Click Turn app into sales channel again to confirm that you want to convert your app into a sales channel.
  2. Click Save.

After you save your changes, your app will be set as a sales channel.

Request Payment Processing

After you have converted your app to a sales channel, you can request payment processing to use the Checkout API with credit cards. Shopify supports a variety of payment processing methods, including third-party services such as Stripe and Spreedly.

To request payment processing for your sales channel:

  1. From the Sales channel section click Request payment processing.
  2. Select your PCI compliance method, as described in the table below.
PCI compliance method Description
My platform is not PCI compliant You'll need to determine a strategy for processing payments.
My platform uses Stripe You have an existing platform account with Stripe and would like to use Shopify's Stripe integration.
My platform uses a service such as Spreedly to deliver payment tokens You'd like to use Spreedly or similar service for credit card tokenization and PAN forwarding.
My platform has a certificate of compliance If you already have a PCI compliant solution in place, then you can provide Shopify with a certificate of compliance.
  1. Enter a description of your app to process your request faster.
  2. Click Request access.

A request for payment processing can take up to 7 business days. You'll receive a notification when your request is processed.

Authorizing your app with OAuth

This guide describes OAuth in the context of OAuth scopes and webhook subscriptions for sales channel apps. To learn more about OAuth, see the Oauth docs or the advanced public app tutorial that walks through the entire OAuth handshake.

A sales channel app enables merchants to list and sell their products on your marketplace or platform. Sales channel apps are public 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 that 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 Oauth grant screen to request the required scopes. The route should use the following format, 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:

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

You can request the following OAuth access scopes for your sales channel app:

  • read_product_listings
  • read_collection_listings
  • read_checkouts and write_checkouts

For more detailed information, see the OAuth documentation.

Obtaining an 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

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. Make sure 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 you receive 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/product_listings.json endpoint:

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

In response, the API returns the product listings formatted as JSON:


{
  "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've 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. Provide the preferred response format (eg. JSON).

For example:


POST /admin/webhooks.json HTTP/1.1
Host: channelsrule.myshopify.com
X-Shopify-Access-Token: 35df6efd065b8ce72dca9493e5ec34c5
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.

Completing a payment using web URL

After you have returned a product and product variants you can complete a checkout using the Checkout API. The Checkout API returns a web_url parameter that you can use for redirecting a customer to Shopify's web checkout experience. This is the most straightforward approach if your app does not require a fully customizable checkout experience.

To create a checkout and return the web URL, send a POST request to the admin/checkouts.json endpoint:

curl -X POST -H "X-Shopify-Access-Token: 35df6efd065b8ce72dca9493e5ec34c5" -H "Content-Type: application/json" "https://{shop}.myshopify.com/admin/checkouts.json" -d @checkout.json

where {shop} is the domain of your test shop, and checkouts.json is a JSON file like the following:

{
  "checkout": {
    "line_items": [
      {
        "variant_id": 26756068422,
        "quantity": 1
      }
    ]
  }
}

In response, the API returns the Checkout object including the web_url parameter:

https://checkout.shopify.com/123456/checkouts/70b2b9d661c32de41fb130cd04e085c2

You can redirect a customer to this URL for Shopify's web checkout experience.

Next steps