Checkout guide

This guide covers creating a checkout in Shopify, and completing it using Shopify's web checkout form. You'll learn how to query for the required line item data, and properly use the checkoutCreate mutation. The guide also covers modifying the checkout by adding line items and modifying the shipping address, before redirecting the user to Shopify's web checkout form.

Prerequisites

This guide assumes you have completed our Getting started guide, and that you are authenticated with the Storefront API. The guide also assumes that you've created product variants in your test shop.

The code examples in this guide can be run in GraphiQL or your preferred HTTP client.

Querying for data

Mutations often require that data is first obtained by running a query. In the case of checkoutCreate, you need to return product variants, before you can populate the checkout input fields with the required line item data.

The following query returns the first two products from your test shop, and specifies the return fields of the payload object that you want back from the server. When specifying the return fields you must include nested subfields until you return only scalars, as described in the spec.


query {
  shop{
    products(first: 2) {
      edges {
        node {
          variants(first: 2) {
            edges {
              node {
                id
              }
            }
          }
        }
      }
    }
  }
}

The above query returns the following data object:

{
  "data": {
    "shop": {
      "products": {
        "edges": [
          {
            "node": {
              "variants": {
                "edges": [
                  {
                    "node": {
                      "id": "Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0VmFyaWFudC8x"
                    }
                  },
                  {
                    "node": {
                      "id": "Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0VmFyaWFudC8x"
                    }
                  }
                ]
              }
            }
          }
        ]
      }
    }
  }
}

Creating 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.

mutation {
  checkoutCreate(input: {
    lineItems: [{ variantId: "Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0VmFyaWFudC80", quantity: 1 }]
  }) {
    checkout {
       id
       webUrl
       lineItems(first: 5) {
         edges {
           node {
             title
             quantity
           }
         }
       }
    }
  }
}

Let’s examine this mutation in more detail:

checkoutCreate(input: {
  lineItems: [{ variantId: "Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0VmFyaWFudC80", quantity: 1}]})

In the above 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.

{
  checkout {
     id
     webUrl
     lineItems(first: 5) {
       edges {
         node {
           title
           quantity
         }
       }
     }
  }
}

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.

If the mutation is valid, then the following response is returned:

{
  "data": {
    "checkoutCreate": {
      "checkout": {
        "id": "Z2lkOi8vc2hvcGlmeS9DaGVja291dC84NGY5YWEwODVkNTkzNTFmZTg3MjgxNjQ5NmJiMzFkZD9rZXk9MjAwNzg2Y2QxN2U0NDg3NjY1ZjQzMmYwYWI3MThkMGU=",
        "webUrl": "https://checkout.myshopify.io/1/checkouts/84f9aa085d59351fe872816496bb31dd?key=200786cd17e4487665f432f0ab718d0e",
        "lineItems": {
          "edges": [
            {
              "node": {
                "title": "Blue Shirt",
                "quantity": 1
              }
            }
          ]
        }
      }
    }
  }
}

Modifying the Checkout

After creating the checkout using checkoutCreate you can modify it by adding additional line items, or the customer's shipping address.

Adding Items to a Checkout

To add items to a checkout, you can use the checkoutLineItemsAdd mutation.

The mutation below adds items using the checkout id and the lineItems array:


mutation {
  checkoutLineItemsAdd(lineItems: [{ variantId: "Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0VmFyaWFudC8z", quantity: 1 }], checkoutId: "Z2lkOi8vc2hvcGlmeS9DaGVja291dC8wN2U2M2JjYWIyYjUzZGM2YWM0NmNiY2I2YWJiY2E1Yj9rZXk9NGFjNjZmZjNjYTJhOGQyYzI1YjQzZDFhNmI0MGQ5MDU=",
  ) {
    checkout {
       id
       lineItems(first:2) {
         edges {
           node {
             id
             title
             quantity
           }
         }
       }
    }
  }
}

A successful mutation returns the following data object:

{
  "data": {
    "checkoutLineItemsAdd": {
      "checkout": {
        "id": "Z2lkOi8vc2hvcGlmeS9DaGVja291dC84NGY5YWEwODVkNTkzNTFmZTg3MjgxNjQ5NmJiMzFkZD9rZXk9MjAwNzg2Y2QxN2U0NDg3NjY1ZjQzMmYwYWI3MThkMGU=",
        "lineItems": {
          "edges": [
            {
              "node": {
                "id": "Z2lkOi8vc2hvcGlmeS9DaGVja291dExpbmVJdGVtLzE2ZDAyZGI2ZDI4MzRjZjA5ZTViZDZmZGY5M2I0MTUzP2NoZWNrb3V0PTg0ZjlhYTA4NWQ1OTM1MWZlODcyODE2NDk2YmIzMWRk",
                "title": "Blue Shirt",
                "quantity": 2
              }
            }
          ]
        }
      }
    }
  }
}

Populating Shipping Address

Before you can properly complete a checkout you need to set the customer shipping address, using the CheckoutShippingAddressUpdate mutation. The mutation below defines the customer's shipping address using GraphQL variables:

mutation checkoutShippingAddressUpdate($shippingAddress: MailingAddressInput!, $checkoutId: ID!) {
  checkoutShippingAddressUpdate(shippingAddress: $shippingAddress, checkoutId: $checkoutId) {
    userErrors {
      field
      message
    }
    checkout {
      id
      shippingAddress {
        firstName
        lastName
        address1
        province
        country
        zip
      }
    }
  }
}

GraphQL Variables:


{
  "shippingAddress": {
    "lastName": "Doe",
    "firstName": "John",
    "address1": "123 Test Street",
    "province": "QC",
    "country": "Canada",
    "zip": "H3K0X2",
    "city": "Montreal"
  },

   "checkoutId": "Z2lkOi8vc2hvcGlmeS9DaGVja291dC8wN2U2M2JjYWIyYjUzZGM2YWM0NmNiY2I2YWJiY2E1Yj9rZXk9NGFjNjZmZjNjYTJhOGQyYzI1YjQzZDFhNmI0MGQ5MDU="
}

A successful mutation returns the following data object:

{
  "data": {
    "checkoutShippingAddressUpdate": {
      "userErrors": [],
      "checkout": {
        "id": "Z2lkOi8vc2hvcGlmeS9DaGVja291dC8wN2U2M2JjYWIyYjUzZGM2YWM0NmNiY2I2YWJiY2E1Yj9rZXk9NGFjNjZmZjNjYTJhOGQyYzI1YjQzZDFhNmI0MGQ5MDU=",
        "shippingAddress": {
          "firstName": "John",
          "lastName": "Doe",
          "address1": "123 Test Street",
          "province": "Quebec",
          "country": "Canada",
          "zip": "H3K0X2"
        }
      }
    }
  }
}

Completing the Checkout

After you've finished creating and performing any updates to the checkout, the simplest way to complete it 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:


query {
  node(id:"Z2lkOi8vc2hvcGlmeS9DaGVja291dC8wN2U2M2JjYWIyYjUzZGM2YWM0NmNiY2I2YWJiY2E1Yj9rZXk9NGFjNjZmZjNjYTJhOGQyYzI1YjQzZDFhNmI0MGQ5MDU=" ) {
    ... 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": "Z2lkOi8vc2hvcGlmeS9DaGVja291dC8wN2U2M2JjYWIyYjUzZGM2YWM0NmNiY2I2YWJiY2E1Yj9rZXk9NGFjNjZmZjNjYTJhOGQyYzI1YjQzZDFhNmI0MGQ5MDU=",
      "webUrl": "https://checkout.myshopify.io/1/checkouts/07e63bcab2b53dc6ac46cbcb6abbca5b?key=4ac66ff3ca2a8d2c25b43d1a6b40d905"
    }
  }
}

Next steps

You might find the following resources useful if you want to know more about the concepts introduced in this guide: