All Tutorials

Build a sales channel with the Checkout API

All Tutorials

Build a sales channel with the Checkout API

Build a sales channel with the Checkout API

This guide teaches you how to enable payments so that customers can place orders for merchants’ products. The guide also covers how you can bill for your app to make money from your sales channel. For purposes of example, we'll build a sales channel that enables buyers to purchase a single merchant's products from your platform. When you build a sales channel you can use either the Admin API or Storefront API depending on your business case and the needs of your app.

Prerequisites

This guide assumes that you're familiar with the following:

Overview

By building a sales channel for Shopify, you can connect merchants' products with buyers on web, mobile and in-game. For example, you could use the Admin API to build an app that allows merchants to integrate products, orders, and customers with your channel. You could also use the Storefront and Admin APIs to develop a mobile app builder by leveraging the Mobile Buy SDKs.

Payments and order management

Building a sales channel with the Checkout API represents lower integration effort because Shopify makes it easy to handle the complexities of payment processing:

  • Shopify offers a variety of payment processing options, depending on your business case and the needs of your app.
  • When you use the Checkout API, Shopify handles paying out to the merchant for you.
  • If you use the Billing API, then it's easier to charge merchants platform fees.
  • Shopify keeps track of orders and fulfillments.
  • Shopify handles disputes, refunds or cancellations.

Creating and completing checkouts

After you've imported a merchant's products, you can accept and process payments for them by creating and completing checkouts. You can do this either using the Admin API or using the Storefront API.

Regardless of what API you choose, checkout creation and completion follows a similar flow and involves similar Shopify resources:

  1. Obtain the line item data necessary to create the checkout object
  2. Specify the shipping information (address, rate) and customer information
  3. Complete the checkout using the payment completion option that is right for your app:
    • Shopify web checkout
    • third party tokenization service (Stripe, Spreedly)
    • Shopify card vault

Checkout example

  • REST Admin API
  • Storefront API

For demonstrative purposes, this example shows the checkout creation method that represents the lowest amount of integration effort. Your app can provide checkout links to Shopify's web checkout for each product. This lets your platform use Shopify's web checkout instead of building your own native checkout form.

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/api/2021-04/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.

To complete a checkout with the Storefront API, redirect the customer to Shopify's web checkout form using the returned webUrl field. At any point during the checkout flow, you can redirect the user to this form by querying the webUrl field on the Checkout:

query {
  node(id:"Z2lkOi8vc2hvcGlmeS9DaGVja291dC81ZDliYTZjOTlhNWY4YTVhNTFiYzllMzlmODEwNTNhYz9rZXk9NWIxZTg5NDQzNTZkMjMxOGU1N2ZlNjQwZDJiNjY1M2Y=" ) {
    ... on Checkout {
      id
      webUrl
    }
  }
}

Notice the inline fragment ...on Checkout. This is required to show which type should be queried for using id. Starting from the query root, node is an interface that implements the type Checkout. You can pass the id of the Checkout to the node interface, and the inline fragment indicates that id should be passed to the Checkout type.

A successful query to the Checkout object for webUrl returns the following data object:

{
  "data": {
    "node": {
      "id": "Z2lkOi8vc2hvcGlmeS9DaGVja291dC81ZDliYTZjOTlhNWY4YTVhNTFiYzllMzlmODEwNTNhYz9rZXk9NWIxZTg5NDQzNTZkMjMxOGU1N2ZlNjQwZDJiNjY1M2Y=",
      "webUrl": "https://checkout.myshopify.io/1/checkouts/07e63bcab2b53dc6ac46cbcb6abbca5b?key=4ac66ff3ca2a8d2c25b43d1a6b40d905"
    }
  }
}

Payouts

Shopify processes the checkouts and handles payouts to the merchants for you.

Get paid

You can use Shopify's Billing API to charge merchants for your sales channel app. When using the Billing API, you can either charge merchants a recurring monthly subscription, or take a commission on sales by creating usage charges. Whichever charging model you use, you need to first create an appSubscription resource. Then, for commission-based sales, you need to create usage charges.

Recurring billing

You can use the appSubscriptionCreate mutation to create a recurring charge. The mutation returns the app subscription ID.

Charging commissions

Charging commissions requires two steps:

If you're charging commissions, then you need to be aware of how your app's fees impact merchant payouts, and how Shopify's platform fee works. The following diagram shows the lifecycle of this process. For demonstrative purposes, the app needs to charge 10 % fees on $100 in sales.

Sales channel get paid