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
- 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
- Cart metafields
- 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 your application can pass 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 Using Auto-Generated Tokens in Stencil Themes.
For more information, see Creating a Token in the GraphQL Storefront API Overview 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
# 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
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
# 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
}
]
}
}
}
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
- GraphQL Storefront API Overview: Using auto-generated tokens in Stencil themes
- 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