All Tutorials

Build a sales channel with the Orders API

All Tutorials

Build a sales channel with the Orders API

Build a sales channel with the Orders 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 merchants for your app to make money from your sales channel. For the purpose of this tutorial, we'll build an example marketplace channel that enables buyers to purchase from multiple Shopify merchants in a shopping cart.


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


Building with the Orders API works best for apps that enable buyers to buy from multiple merchants in a single shopping cart. The integration effort is higher with these channels because you need to handle the following:

  • Collect the merchants's banking details during onboarding
  • Pay out to the merchant
  • Import orders to Shopify using the Orders API
  • Keep track of order status / read fulfillment events
  • Stay in sync for refunds

Payments and order management

If you're building with the Orders API to enable the purchase of products from multiple merchants in a single shopping cart, then you can do the following:

  • Control the checkout experience yourself, including paying out to the merchant, and taking your marketplace fees
  • Sync all orders from your app with Shopify. This includes updating orders with any relevant changes.
  • Keep your app up-to-date with fulfillment events from Shopify
  • Mange any disputes, refunds or cancellations using the appropriate Shopify APIs

Creating checkouts

To build a checkout experience for your app's users, you'll need to build your own checkout solution. Your checkout flow needs to create the checkout, add shipping information, and process payment methods.


You'll need have a system in place for collecting merchant payment details (such as banking information), and for paying out to merchants. One option is to use the onboarding flow of your sales channel app to collect the merchant's payment information. You could add payment information collection as part of your additional onboarding steps.

If instead you use the Checkout API, then Shopify processes payments and pays out to the merchants for you.

Syncing orders with Shopify

For every order generated by your marketplace app, you need to create a corresponding order in Shopify. You can make the following call to the Shopify API with an order object in the body of the request to create an order:

POST https://{shop}

This returns an order object with an id property that you can use to stay in sync with your app's changes.

Order updates:

If any changes are made to an order's status by your app, then you need to make sure those are communicated to Shopify. To do this, you can update the order with a note field telling the merchant what needs to be done.

PUT https://{shop}{order_id}.json

This returns the updated order object with the updated information in the note field.


After the order is imported into Shopify, the merchant can fulfill it and track it. Your app can read fulfillments to stay up-to-date with fulfillment events. Because you're building a marketplace app, you want to keep your app up-to-date with events for steps in the shipping pipeline to track the successful shipment of the orders. This way, your app has the most up-to-date information if you need to take any customer support requests about the order.

Fulfillment webhooks:

You can configure webhook events for fulfillments using the API by specifying the fulfillment topic in the body of the request:

POST https://{shop}

Then, create an HTTP endpoint on your server to monitor for fulfillment events. You can learn more in Creating an endpoint for webhooks.

Disputes, Refunds, Cancellations

Because you're building a marketplace app, you need to have mechanisms in place to handle the following use cases for refunds, partial refunds, and cancellations:

  • If customer request refunds or cancel orders, then communicate this activity to Shopify using APIs
  • Use webhooks to stay in sync with merchant activities

Customer activities:

If a customer cancels an order in your app, then you need to communicate this to Shopify. To do this, you can cancel the order:

POST https://{shop}{order_id}/cancel.json

In Shopify, a cancellation can only be applied to an entire order.

If a customer refunds an order in your app, then you need to communicate this to Shopify. To do this, you can refund the order:

POST https://{shop}{order_id}/refunds.json

In Shopify, a refund can be per line item.

Merchant activities:

It's possible for merchants to issue refunds, partial refunds or cancellations. For example, a merchant might run out of stock for a particular item, or a customer might fail a fraud check.

You can configure webhook events for orders and refunds to stay up-to-date with merchant activities.

Get paid

Because you're building with the Orders API, you can implement your own mechanism for taking marketplace fees for the sales that merchants make on you marketplace. You can also use Shopify's Billing API, to more easily charge fees to merchants.

Keep in mind that your marketplace app needs to do the following to support an order's full lifecycle:

  • Create a checkout to process and transfer sales for the merchant
  • Charge marketplace fees to merchants and subtract them from their sales (Sales channel apps that use the Billing API can benefit from features such as subscription billing and usage charges).
  • Be aware of Shopify’s platform fee

The following diagram shows the lifecycle of this process. For the purposes of example, the app needs to charge 10 % fees on $100 in sales.

Marketplace get paid