Docs
Storefront
Cart and checkout
API guides
GraphQL Storefront

GraphQL Storefront API: Carts and Checkout

BigCommerce's GraphQL Storefront API provides the same access to cart and checkout objects as the REST Storefront API. Having access to cart and checkout data in the graph alongside related data makes it easier to build headless storefront applications.

Developers can use frontend GraphQL to create an end-to-end shopper experience. Cart and checkout-related mutations and queries can do the following:

  • Create a cart
  • Add products to a cart
  • View or manage a cart
  • Create cart redirect URLs
  • Create cart metafields
  • Fill out checkout details
  • Determine the cost of shipping and select a shipping method
  • Complete checkout by converting a cart into an order
  • Generate a payment access token

Limitations As of this writing, the GraphQL Storefront API does not support the following features:

  • File upload product options
  • Buy Online, Pick up in Store
  • Checkout directly from the Product Details Page, or Buy Now carts

Tokens

To make requests, create a store-level API account with one or more of the following token creation OAuth scopes:

  • Storefront API Tokens
  • Storefront API Customer Impersonation Tokens

No additional scopes are required to use the GraphQL Storefront API.

To generate a bearer token to authenticate calls to the GraphQL Storefront API, use either the Create a storefront token or the Create a customer impersonation token REST endpoint. On a Stencil storefront, you can also access a token at render time using a Handlebars property. Learn more about Authenticating requests to the GraphQL Storefront API.

For more information, see Creating a token in Authenticating requests to the GraphQL Storefront API and dynamic tokens in the Authentication and example requests article.

Handling payments

To handle payments, use the Payments API (Overview).

For PCI compliance-related reasons, the GraphQL Storefront API does not handle payments. You can use the Payments API (Reference) to process payments.

The GraphQL Storefront API returns the checkout ID and order ID, which you can use to Get accepted payment methods and Create a payment access token. You can also generate a payment access token using the GraphQL Storefront completeCheckout mutation.

The GraphQL Storefront API returns the customer ID, which you can use to Get stored payment instruments. To learn more about authenticating REST endpoints, locate the Authentication section at the top of each endpoint, then click Show Details.

Gift certificates are a type of payment instrument similar to a debit card, so the Payments API must apply the gift certificate to the checkout.

The API account you use to process payments must have the scopes specified in the Payments API Overview.

Example queries and mutations

Create a cart using a simple product

Example mutation: Create a cart (simple)
# Creates a new cart, adding a simple product.
# In the GraphQL Playground, this will fail if you already have a cart.
 
mutation createCartSimple($createCartInput: CreateCartInput!) {
  cart {
    createCart(input: $createCartInput) {
      cart {
        entityId
        lineItems {
          physicalItems {
            name
            quantity
          }
          digitalItems {
            name
            quantity
          }
          giftCertificates {
            name
          }
          customItems {
            name
            quantity
          }
        }
      }
    }
  }
}
GraphQL variables
{
  "createCartInput": {
    "lineItems": [
      {
        "quantity": 1,
        "productEntityId": 111
      }
    ]
  }
}

Get a cart

If using the getCart query with customer impersonation tokens, you must include the cart's entityId.

Example query: Get a cart
query getCart {
  site {
    cart {
      entityId
      currencyCode
      isTaxIncluded
      baseAmount {
        currencyCode
        value
      }
      discountedAmount {
        currencyCode
        value
      }
      amount {
        currencyCode
        value
      }
      discounts {
        entityId
        discountedAmount {
          currencyCode
          value
        }
      }
      lineItems {
        physicalItems {
          entityId
          parentEntityId
          variantEntityId
          productEntityId
          sku
          name
          url
          imageUrl
          brand
          quantity
          isTaxable
          discounts {
            entityId
            discountedAmount {
              currencyCode
              value
            }
          }
          discountedAmount {
            currencyCode
            value
          }
          couponAmount {
            currencyCode
            value
          }
          listPrice {
            currencyCode
            value
          }
          originalPrice {
            currencyCode
            value
          }
          salePrice {
            currencyCode
            value
          }
          extendedListPrice {
            currencyCode
            value
          }
          extendedSalePrice {
            currencyCode
            value
          }
          isShippingRequired
          selectedOptions {
            entityId
            name
            ... on CartSelectedCheckboxOption {
              value
              valueEntityId
            }
            ... on CartSelectedDateFieldOption {
              date {
                utc
              }
            }
            ... on CartSelectedFileUploadOption {
              fileName
            }
            ... on CartSelectedMultiLineTextFieldOption {
              text
            }
            ... on CartSelectedMultipleChoiceOption {
              value
              valueEntityId
            }
            ... on CartSelectedNumberFieldOption {
              number
            }
            ... on CartSelectedTextFieldOption {
              text
            }
          }
          giftWrapping {
            name
            amount {
              currencyCode
              value
            }
            message
          }
        }
        digitalItems {
          entityId
          parentEntityId
          variantEntityId
          productEntityId
          sku
          name
          url
          imageUrl
          brand
          quantity
          isTaxable
          discounts {
            entityId
            discountedAmount {
              currencyCode
              value
            }
          }
          discountedAmount {
            currencyCode
            value
          }
          couponAmount {
            currencyCode
            value
          }
          listPrice {
            currencyCode
            value
          }
          originalPrice {
            currencyCode
            value
          }
          salePrice {
            currencyCode
            value
          }
          extendedListPrice {
            currencyCode
            value
          }
          extendedSalePrice {
            currencyCode
            value
          }
          selectedOptions {
            entityId
            name
            ... on CartSelectedCheckboxOption {
              value
              valueEntityId
            }
            ... on CartSelectedDateFieldOption {
              date {
                utc
              }
            }
            ... on CartSelectedFileUploadOption {
              fileName
            }
            ... on CartSelectedMultiLineTextFieldOption {
              text
            }
            ... on CartSelectedMultipleChoiceOption {
              value
              valueEntityId
            }
            ... on CartSelectedNumberFieldOption {
              number
            }
            ... on CartSelectedTextFieldOption {
              text
            }
          }
        }
        giftCertificates {
          entityId
          name
          theme
          amount {
            currencyCode
            value
          }
          isTaxable
          sender {
            name
            email
          }
          recipient {
            name
            email
          }
          message
        }
        customItems {
          entityId
          sku
          name
          quantity
          listPrice {
            currencyCode
            value
          }
          extendedListPrice {
            currencyCode
            value
          }
        }
        totalQuantity
      }
      createdAt {
        utc
      }
      updatedAt {
        utc
      }
      locale
    }
  }
}

Add cart line items

Example mutation: Add cart line items
# Adds another line item.
# Add the cart ID to the GraphQL variables, or the mutation will fail. 
mutation addCartLineItems($addCartLineItemsInput: AddCartLineItemsInput!) {
  cart {
    addCartLineItems(input: $addCartLineItemsInput) {
      cart {
        entityId
      }
    }
  }
}
GraphQL variables
{
  "addCartLineItemsInput": {
    "cartEntityId": "bb916deb-ddd6-4586-b65b-b8385e0e7a9d",
    "data": {
      "lineItems": [
        {
          "quantity": 1,
          "productEntityId": 107
        }
      ]
    }
  }
}

Create a cart redirect URL

You can use a cart redirect URL for embedded checkouts or to redirect your
checkout. You need a cartEntity ID. To create a cartEntity ID, use the
create a cart mutation.

Example mutation: Create cart redirect URL
mutation{
 cart {
     createCartRedirectUrls(input:{
         cartEntityId: "dc5e7b24-0047-4b3e-b16b-2cdc90943b86"}) {
         redirectUrls{
             embeddedCheckoutUrl
             redirectedCheckoutUrl
         }
     }
 
 }
}

Create cart metafield

The current platform limit is 250 metafields for a single cart. When you create metafields using the createCartMetafield mutation, the default namespace is bc_storefront.

Example mutation: Create cart metafield
mutation createCartMetafield {
 
cart {
  createCartMetafield(input:{
    cartEntityId: "9f3ffbd5-0066-4854-9e95-5bf30bfbcc87"
    data: {
      key: "color"
      value: "blue"
    }
  }) {
    metafield {
      id
      entityId
      key
      value
    }
    errors {
      ...on Error {
        message
      }
    }
  }
}
}

Delete cart

Example mutation: Delete cart
# Delete your cart in the GraphQL Playground, which will enable you to create a new cart.
# Add the cart ID to the GraphQL variables, or the mutation will fail.
 
mutation deleteCart($deleteCartInput: DeleteCartInput!) {
  cart {
    deleteCart(input: $deleteCartInput) {
      deletedCartEntityId
    }
  }
}
GraphQL variables
{
  "deleteCartInput": {
    "cartEntityId": "bb916deb-ddd6-4586-b65b-b8385e0e7a9d"
  }
}

Get Checkout

Example query: Get checkout
query getCheckout {
  site {
    checkout {
      entityId
      billingAddress {
        ...CheckoutBillingAddressFields
      }
      shippingConsignments {
        ...CheckoutShippingConsignmentFields
      }
      order {
        entityId
      }
      shippingCostTotal {
        ...MoneyFields
      }
      giftWrappingCostTotal {
        ...MoneyFields
      }
      handlingCostTotal {
        ...MoneyFields
      }
      taxTotal {
        ...MoneyFields
      }
      taxes {
        ...CheckoutTaxFields
      }
      subtotal {
        ...MoneyFields
      }
      grandTotal {
        ...MoneyFields
      }
      createdAt {
        utc
      }
      updatedAt {
        utc
      }
      customerMessage
      outstandingBalance {
        ...MoneyFields
      }
      coupons {
        ...CheckoutCouponFields
      }
      promotions {
        ...CheckoutPromotionFields
      }
    }
  }
}
 
fragment CheckoutConsignmentAddressFields on CheckoutConsignmentAddress {
  ...CheckoutAddressFields
}
 
fragment CheckoutBillingAddressFields on CheckoutBillingAddress {
  entityId
  ...CheckoutAddressFields
}
 
fragment CheckoutAddressFields on CheckoutAddress {
  firstName
  lastName
  email
  company
  address1
  address2
  city
  stateOrProvince
  stateOrProvinceCode
  countryCode
  postalCode
  phone
  customFields {
    entityId
    ... on CheckoutAddressCheckboxesCustomField {
      valueEntityIds
    }
    ... on CheckoutAddressDateCustomField {
      date {
        utc
      }
    }
    ... on CheckoutAddressMultipleChoiceCustomField {
      valueEntityId
    }
    ... on CheckoutAddressNumberCustomField {
      number
    }
    ... on CheckoutAddressPasswordCustomField {
      password
    }
    ... on CheckoutAddressTextFieldCustomField {
      text
    }
  }
}
 
fragment CheckoutShippingConsignmentFields on CheckoutShippingConsignment {
  entityId
  address {
    ...CheckoutConsignmentAddressFields
  }
  availableShippingOptions {
    ...CheckoutAvailableShippingOptionFields
  }
  selectedShippingOption {
    ...CheckoutSelectedShippingOptionFields
  }
  coupons {
    ...CheckoutCouponFields
  }
  shippingCost {
    ...MoneyFields
  }
  handlingCost {
    ...MoneyFields
  }
  lineItemIds
}
 
fragment CheckoutAvailableShippingOptionFields on CheckoutAvailableShippingOption {
  entityId
  description
  type
  imageUrl
  cost {
    ...MoneyFields
  }
  transitTime
  isRecommended
}
 
fragment CheckoutSelectedShippingOptionFields on CheckoutSelectedShippingOption {
  entityId
  description
  type
  imageUrl
  cost {
    ...MoneyFields
  }
  transitTime
}
 
fragment MoneyFields on Money {
  value
  currencyCode
}
 
fragment CheckoutCouponFields on CheckoutCoupon {
  entityId
  code
  couponType
  discountedAmount {
    ...MoneyFields
  }
}
 
fragment CheckoutTaxFields on CheckoutTax {
  name
  amount {
    ...MoneyFields
  }
}
 
fragment CheckoutPromotionFields on CheckoutPromotion {
  banners {
    entityId
    type
    locations
    text
  }
}

Add checkout billing address

Example mutation: Add checkout billing address
mutation addCheckoutBillingAddress($addCheckoutBillingAddressInput: AddCheckoutBillingAddressInput!) {
  checkout {
    addCheckoutBillingAddress(input: $addCheckoutBillingAddressInput) {
      checkout {
        entityId
      }
    }
  }
}
GraphQL variables
{
  "addCheckoutBillingAddressInput": {
    "checkoutEntityId": "812ece1a-da23-46eb-ab6b-c2ee210aae54",
    "data": {
      "address": {
        "firstName": "Joe",
        "lastName": "Blogs",
        "email": "[email protected]",
        "company": "BlogIndustries",
        "address1": "123 Yar st",
        "address2": "",
        "city": "RWC",
        "stateOrProvince": "CA",
        "stateOrProvinceCode": "CA",
        "countryCode": "US",
        "postalCode": "94061",
        "phone": "6501231212",
        "shouldSaveAddress": false
      }
    }
  }
}

Add a checkout shipping consignment

Example mutation: Add a checkout shipping consignment
mutation addCheckoutShippingConsignments($addCheckoutShippingConsignmentsInput: AddCheckoutShippingConsignmentsInput!) {
  checkout {
    addCheckoutShippingConsignments(input: $addCheckoutShippingConsignmentsInput) {
      checkout {
        entityId
        shippingConsignments {
          entityId
          availableShippingOptions {
            entityId
          }
          selectedShippingOption {
            entityId
          }
        }
      }
    }
  }
}
GraphQL variables
{
  "addCheckoutShippingConsignmentsInput": {
    "checkoutEntityId": "812ece1a-da23-46eb-ab6b-c2ee210aae54",
    "data": {
      "consignments": [
        {
          "address": {
            "firstName": "Joe",
            "lastName": "Blogs",
            "email": "[email protected]",
            "company": "BlogIndustries",
            "address1": "123 Yar st",
            "city": "RWC",
            "stateOrProvince": "CA",
            "stateOrProvinceCode": "CA",
            "countryCode": "US",
            "postalCode": "94061",
            "phone": "6501231212",
            "shouldSaveAddress": false
          },
          "lineItems": [
            {
              "lineItemEntityId": "0a281902-d548-4d2e-a930-dc2aae9bfc39",
              "quantity": 1
            }
          ]
        }
      ]
    }
  }
}

Select checkout shipping option

Example mutation: Select checkout shipping option
  mutation selectCheckoutShippingOption($selectCheckoutShippingOptionInput: SelectCheckoutShippingOptionInput!) {
    checkout {
      selectCheckoutShippingOption(input: $selectCheckoutShippingOptionInput) {
        checkout {
          entityId
        }
      }
    }
  }
GraphQL variables
  {
    "selectCheckoutShippingOptionInput": {
      "checkoutEntityId": "acd6f2ca-85c1-4b5f-8dab-d7d80521ecc5",
      "consignmentEntityId": "6478ff925d33a",
      "data": {
        "shippingOptionEntityId": "9ba45e71fe66e1cd757f022dcae331b0"
      }
    }
  }

Complete checkout

Example mutation: Complete checkout
  mutation completeCheckout($completeCheckoutInput: CompleteCheckoutInput!) {
    checkout {
      completeCheckout(input:$completeCheckoutInput) {
        orderEntityId
        paymentAccessToken
      }
    }
  }
GraphQL variables
{
  "completeCheckoutInput": {
    "checkoutEntityId": "812ece1a-da23-46eb-ab6b-c2ee210aae54"
  }
}

Giving feedback

We invite you to give feedback on the GraphQL Storefront schema and the capabilities of the API to let us know if it meets your needs. In particular, we want to know about anything that seems confusing, or anything that you think is missing. We want to ensure that this API meets your needs, and we're open to adding features.

Join our Developer Community to share your feedback with us in the BigCommerceDevs Slack or on our Discord server.

Resources

Articles

API reference

Storefront tokens

Payments API

REST Management API: Customers

Community

Did you find what you were looking for?
MetafieldsREST Storefront