All Tutorials

Build a sales channel with cart permalinks

All Tutorials

Build a sales channel with cart permalinks

Build a sales channel with cart permalinks

This guide teaches you how to build links to Shopify checkouts with pre-loaded items, so that customers can place orders for merchants’ products using your sales channel app. The guide also covers how to add an additional parameter to the permalink, so that you can attribute an order to your sales channel.

Prerequisites

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

Overview

You can use cart permalinks to build a sales channel app that makes it easy for merchants to add their products to your site. Cart permalinks are pre-built links that take customers directly to a shopping cart or checkout. These permalinks work best for apps that enable buyers to buy items from a single merchant in a cart.

Building a sales channel with permalinks requires the lowest integration effort for several reasons:

  • Your app doesn't need to create checkouts or process payments
  • Your app doesn't need to sync orders, handle disputes, or mange refunds

Payments and order management

You can use permalinks to manage Shopify checkouts as follows:

  • Apply one or more variant IDs to a cart or checkout
  • Append checkout parameters to include shipping information (address, rate) and customer information

Because you're not using the Checkout API, you don't need to complete checkouts and payment processing considerations (eg. third party tokenization services, Shopify card vault etc.).

For demonstrative purposes, this example shows how to create a link to a checkout with two product variants applied, each with a quantity of one.

To create the checkout permalink, specify a URL to the merchant's shop formatted as follows:

http://yourstore.com/cart/#{variant_id}:#{quantity}(,...)

Example:

In the example below 70881412 and 70881382 are the product variant IDs and 1 is the quantity:

http://your-store.myshopify.com/cart/70881412:1,70881382:1

Modify the checkout parameters

This example shows how you can append checkout query parameters in the cart permalink URL.

To modify a permalink, specify a URL to the merchant's shop formatted as follows:

http://your-store.myshopify.com/cart/{variant_id}:{quantity}?checkout[email]=somebody@store.com&checkout[shipping_address][city]=thisismyhometown

In the example, [email] represents any of the possible checkout fields in the form, and [shipping_address][city] shows how you can use nesting to populate child fields.

List of supported checkout parameters:

Checkout parameter Description
checkout[email] Email of the customer making the checkout.
checkout[shipping_address][first_name] Address [first_name].
checkout[shipping_address][last_name] Address [last_name]
checkout[shipping_address][address1] Address [address1]
checkout[shipping_address][address2] Address [address2]
checkout[shipping_address][city] Address [city]
checkout[shipping_address][zip] Address [zip]

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:

Attribution with the Storefront access token

To attribute an order to a sales channel or app, you can add an additional parameter to the permalink. Merchants can view sales attributions in the Sales by Channel report, which shows the name of the channel or app that the customer used to place the order. Sales attributions also appear on the sidebar in Shopify admin. You can specify a storefront access token in the cart permalink as shown in the following example:

/cart/70881412:1,70881382:1?access_token=#{access_token}