Create a checkout with the Storefront API
You can use the Storefront API to create a checkout.
This guide shows you how to create a checkout in Shopify. It also covers how to update the checkout, including changing line items, populating the shipping address, and setting the shipping rate. The final sections of the guide describe how to associate a customer with a checkout and complete the checkout.
The mutations in this tutorial that complete checkouts are available only for sales channels.
Requirement
Anchor link to section titled "Requirement"- You've completed the Getting started with the Storefront API guide.
You're familiar with querying products and collections.
If instead of completing the Getting started, you've turned your app into a sales channel and requested and been approved for payment processing.
You've created products and product variants in your store.
To complete the checkout in this tutorial using the
checkoutCompleteWithTokenizedPaymentV3
mutation, you need to have thewrite_checkouts_payments
scope enabled for your app. The scope is enabled by requesting payment processing.You've familiarized yourself with the concept of checkouts.
Step 1: Query product variants
Anchor link to section titled "Step 1: Query product variants"Before you can create a checkout, you need to return product variants so that you can populate the checkout input fields with the required line item data.
The following query returns the first two product variants from your store, and specifies the ID as the payload object:
Step 2: Create the checkout
Anchor link to section titled "Step 2: Create the checkout"You can use the checkoutCreate
mutation to create a new checkout. The return fields include the Checkout
object with the webUrl
field.
The following mutation creates the checkout and returns the checkout id
, the added line items, and the webUrl
field that you'll use later to redirect the user to the web checkout.
The checkoutCreate
mutation in detail
Anchor link to section titled "The checkoutCreate mutation in detail"Let’s examine the checkoutCreate
mutation in more detail.
In the following snippet, checkoutCreate
is the name of the mutation, and input
is the required argument. The required argument value is an input object type that includes the lineItems
field, an array that includes variantId
and quantity
as required fields.
The rest of the mutation defines the return fields for the payload object. The return fields of the checkout
show that id
and webUrl
fields can be returned, and that a lineItems
connection can be specified.
The lineItems
connection data must be accessed with edges. The node at the end of the CheckoutLineItemConnection
type is a CheckoutLineItem
and requires title
and quantity
:
Step 3: Update the checkout
Anchor link to section titled "Step 3: Update the checkout"After creating the checkout using the checkoutCreate
mutation, you can update the checkout by applying a discount code, changing the line items, or updating the customer's shipping address.
You can apply discount codes using the checkoutDiscountCodeApplyV2
mutation. The mutation replaces any discounts that you've already created. To remove a discount, use the checkoutDiscountCodeRemove
mutation.
Change line items on a checkout
Anchor link to section titled "Change line items on a checkout"To change the line items on a checkout, you can use the checkoutLineItemsReplace
mutation. The mutation replaces the checkout's existing lineItems
array with a new array that's specified in the mutation.
The following example replaces the existing line item with two new line items. The checkoutId
argument identifies the checkout to update, and the lineItems
argument specifies the variants and quantities to add to the checkout:
Populate the shipping address
Anchor link to section titled "Populate the shipping address"Before you can properly complete a checkout, you need to set the customer shipping address by using the checkoutShippingAddressUpdateV2
mutation.
The following example defines the customer's shipping address using GraphQL variables:
Set the shipping rate
Anchor link to section titled "Set the shipping rate"You can query Shopify for the shipping rates that are available for the checkout. Then you can select the applicable rate using the handle
of the shippingRates
and apply it to the checkout.
To return the availableShippingRates
, you can query the Checkout
object using node
. The following query returns the shippingRates
for the checkout:
Poll shipping rates
Anchor link to section titled "Poll shipping rates"Because retrieving shipping rates can cause asynchronous recalculation, you might have to poll multiple times to return the list of rates. The following response indicates that you need to poll again:
After you've received the list of rates, you can then set the shippingRateHandle
using the checkoutShippingLineUpdate
mutation:
Step 4: Associate a customer
Anchor link to section titled "Step 4: Associate a customer"You can associate a customer with a checkout so that the customer doesn't have to enter customer information when checking out. You can associate the customer to Shopify's web checkout or to a checkout that will be completed through the API.
Associate customers to web checkouts
Anchor link to section titled "Associate customers to web checkouts"If you're using Shopify's web checkout, then you can use the Multipass resource to log in customers and redirect them to a web checkout link. You can enable Multipass in a Shopify store, obtain the token identifying the customer, and log in the customer.
Redirect the customer to the web checkout URL
Anchor link to section titled "Redirect the customer to the web checkout URL"To get the Multipass token for the customer, you need to provide some customer information. During this step, you can provide a redirect URL using the return_to
field to specify the URL of the web checkout. When customers are redirected to the checkout URL, they stay logged in to the Shopify store.
Associate customers to Storefront API checkouts
Anchor link to section titled "Associate customers to Storefront API checkouts"If you're not using Shopify's web checkout, then you need to get a customer access token to associate the customer with the checkout. You can get the access token using either the customerAccessTokenCreate
or customerAccessTokenCreateWithMultipass mutations.
After you have the customer access token, you can use the checkoutCustomerAssociateV2
mutation.
Associate a customer to a checkout
Anchor link to section titled "Associate a customer to a checkout"After you've created a customer with a customer access token, you can use the token to associate the customer to the checkout. The following mutation uses the customer's access token and the checkout ID to associate the customer with the checkout.
Step 5: Complete the checkout
Anchor link to section titled "Step 5: Complete the checkout"After you've finished creating and performing any updates to the checkout, you can complete the checkout. There are several ways to complete a checkout:
- Use the
webUrl
field to redirect the customer to Shopify's web checkout form. Complete the checkout using one of the following methods:
In order to complete the checkout the totalPrice
needs to be paid. The total price can change depending on duties, taxes and discounts.
Complete a checkout for a logged in customer
Anchor link to section titled "Complete a checkout for a logged in customer"If you complete a checkout for a logged in customer, then the customer is prompted to log in again.
You can't use the X-Shopify-Customer-Access-Token
header to preserve authentication when the customer is associated to the checkout. If the store is on a Shopify Plus plan, then you can use the Multipass resource to preserve authentication and associate the customer with the checkout.
If the customer doesn't have an account, then you can use the customerCreate
mutation to create one.
Shopify web checkout
Anchor link to section titled "Shopify web checkout"The simplest way to complete a checkout is to 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
:
Shopify card vault
Anchor link to section titled "Shopify card vault"You can complete the checkout by sending credit card information to Shopify's PCI-compliant card vault. Then you can use the returned payment vault ID with the checkoutCompleteWithCreditCardv2
mutation.
Get the vault ID
Anchor link to section titled "Get the vault ID"To get the vault ID to complete a payment, you need to send a POST request to the Shopify card vault. The credit card information is sent in the body of the request, and a valid request returns an ID formatted as follows:
Complete the checkout
Anchor link to section titled "Complete the checkout"To complete the checkout, send the payment
information, including the amount
, currencyCode
and billingAddress
fields. Send the payment vault ID as the vaultID
.
3D Secure payments
Anchor link to section titled "3D Secure payments"If you're located in an area impacted by PSD2, then you need to implement 3D Secure payment processing into your app or sales channel. To implement 3D Secure, the following steps are required:
- After completing a checkout with the
checkoutCompleteWithCreditCardV2
mutation, redirect the customer to the URL that's returned by thenextActionUrl
field so that they can complete the 3D Secure authentication. - Poll the checkout until the payment is complete and the
ready
field returnstrue
.
For a detailed guide, refer to Authenticate a payment with 3D Secure.
You can use Shopify's integration with Stripe to tokenize credit cards on behalf of merchants that have enabled Shopify Payments as their payment gateway solution.
You can complete the checkout by sending credit card information to Stripe. Then you can use the returned token with the checkoutCompleteWithTokenizedPaymentV3
mutation.
Setup requirements
Anchor link to section titled "Setup requirements"Shopify's integration with Stripe has the following requirements:
Requirement | Description |
---|---|
The merchant must have Shopify Payments enabled. | Each merchant that installs your app must have Shopify Payments enabled to use the Stripe integration. You can enable Shopify Payments for your store from the payments settings. |
You need a Stripe platform account with Connect integration. | Visit Stripe to sign up for a Connect integration. |
You need access to create tokens on behalf of Shopify's Custom accounts in Stripe. | When your app creates a new checkout for a store with Shopify Payments enabled, Shopify creates a Stripe account for the merchant as part of the Connect integration, and returns the shopifyPaymentsAccountId . You can also use the Storefront API to retrieve the shopifyPaymentsAccountId . You can then get a credit card token from Stripe to complete the payment. To get access, provide Shopify with your Stripe platform account ID. You can query for this ID using the Stripe API. |
Get the Stripe token
Anchor link to section titled "Get the Stripe token"To get a Stripe token for payment, you need to send the credit card information to the Stripe create a card token endpoint. You can use the returned token to complete the payment.
Replace {secret_key}
with the test or live key token used for your Stripe platform account:
Complete the checkout
Anchor link to section titled "Complete the checkout"To complete the checkout, send the payment information in the payment
argument of the checkoutCompleteWithTokenizedPaymentV3
mutation. Send the Stripe token in the paymentData
field.
You can use Spreedly to send customer credit card information to Shopify's PCI compliant card vault. The process of exchanging credit card information for a Shopify payment vault ID is a multi-step process.
To obtain the vault ID, the following flow is observed:
- You get a token from the Spreedly payment_methods endpoint.
- You send the token and credit card information to the Spreedly deliver endpoint.
- You use the returned Shopify vault ID sent to you by Spreedly to complete the checkout with the
checkoutCompleteWithCreditCardV2
mutation.
Setup requirements
Anchor link to section titled "Setup requirements"Shopify's integration with Spreedly has the following requirements:
- You add the Shopify receiver to your Spreedly account.
- You add a credit card in Spreedly.
- You deliver the payment information to Shopify's card vault using Spreedly's deliver endpoint.
Add Shopify as a receiver in Spreedly
Anchor link to section titled "Add Shopify as a receiver in Spreedly"Spreedly lets you distribute vaulted credit card data to non-gateway third parties called receivers. You need to add Shopify as a receiver in your Spreedly account so Spreedly can send credit card information to Shopify's card vault.
To add Shopify as a receiver, send a POST request to the Spreedly receivers endpoint including the receiver
object in the body of the request. The receiver
object includes "shopify"
as the receiver_type
.
Add a credit card in Spreedly
Anchor link to section titled "Add a credit card in Spreedly"To get a vault ID, you first need to tokenize a credit card with Spreedly. This should be done using an iFrame payment form or Spreedly Express for less PCI scope.
To get the token, send a POST request to the Spreedly payment_methods endpoint, and include the credit card information in the body of the request.
Deliver the payment information
Anchor link to section titled "Deliver the payment information"After you get a payment method token, you can get the Shopify card vault ID from the Spreedly deliver endpoint. Spreedly delivers the payment method to Shopify's receiver endpoint, and in response Shopify returns the vault ID.
To get the vault ID, send a POST request to the Spreedly deliver endpoint. You need to include Shopify's receiver token as a path parameter, and the payment method token in the body of the request. This tells Spreedly to deliver the credit card associated with the payment method token to the Shopify card vault. You also need to include properly formatted JSON syntax in the body
object.
Complete the payment
Anchor link to section titled "Complete the payment"After you get the Shopify payment vault ID, you can complete the payment using the checkoutCompleteWithCreditCardV2
mutation. To complete the checkout, send the payment information in the payment
argument of the checkoutCompleteWithCreditCardV2
mutation. Send the vault ID as the vaultId
.
- Learn how to authenticate payments with 3D Secure to process payments for customers in the European Economic Area.
- Learn how to manage customer accounts with the Storefront API.
- Support multiple languages on a storefront with the Storefront API.
- Retrieve metafields with the Storefront API to access additional information from different types of resources.
- Learn about the different tools that you can use to create unique buying experiences anywhere your customers are, including websites, apps, and video games.