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.
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
# 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
}
}
}
}
}
}{
"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.
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
path
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
path
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
# 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
}
}
}
}{
"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.
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.
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
# 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
}
}
}{
"deleteCartInput": {
"cartEntityId": "bb916deb-ddd6-4586-b65b-b8385e0e7a9d"
}
}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
mutation addCheckoutBillingAddress($addCheckoutBillingAddressInput: AddCheckoutBillingAddressInput!) {
checkout {
addCheckoutBillingAddress(input: $addCheckoutBillingAddressInput) {
checkout {
entityId
}
}
}
} {
"addCheckoutBillingAddressInput": {
"checkoutEntityId": "812ece1a-da23-46eb-ab6b-c2ee210aae54",
"data": {
"address": {
"firstName": "Joe",
"lastName": "Blogs",
"email": "joe@example.com",
"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
mutation addCheckoutShippingConsignments($addCheckoutShippingConsignmentsInput: AddCheckoutShippingConsignmentsInput!) {
checkout {
addCheckoutShippingConsignments(input: $addCheckoutShippingConsignmentsInput) {
checkout {
entityId
shippingConsignments {
entityId
availableShippingOptions {
entityId
}
selectedShippingOption {
entityId
}
}
}
}
}
}{
"addCheckoutShippingConsignmentsInput": {
"checkoutEntityId": "812ece1a-da23-46eb-ab6b-c2ee210aae54",
"data": {
"consignments": [
{
"address": {
"firstName": "Joe",
"lastName": "Blogs",
"email": "joe@example.com",
"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
mutation selectCheckoutShippingOption($selectCheckoutShippingOptionInput: SelectCheckoutShippingOptionInput!) {
checkout {
selectCheckoutShippingOption(input: $selectCheckoutShippingOptionInput) {
checkout {
entityId
}
}
}
} {
"selectCheckoutShippingOptionInput": {
"checkoutEntityId": "acd6f2ca-85c1-4b5f-8dab-d7d80521ecc5",
"consignmentEntityId": "6478ff925d33a",
"data": {
"shippingOptionEntityId": "9ba45e71fe66e1cd757f022dcae331b0"
}
}
}Complete checkout
mutation completeCheckout($completeCheckoutInput: CompleteCheckoutInput!) {
checkout {
completeCheckout(input:$completeCheckoutInput) {
orderEntityId
paymentAccessToken
}
}
}{
"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
- GraphQL Storefront API Overview
- Authenticating requests to the GraphQL Storefront API
- Payments API Overview
- Guide to API Accounts: Store-level API accounts
- Guide to API Accounts: OAuth token creation scopes
- Authentication and Example Requests: BigCommerce-generated JWTs