Lab - Query Practice

In this lab, you will:

• Create a cart
• Get a cart
• Add a cart line item
• Create a Cart Redirect URL
• Get a checkout
• Add checkout billing address
• Add shipping consignment
• Select a shipping option
• Complete checkout

Create a Cart Using a Simple Product

In this mutation, we will create a cart using a simple product (ID = 81).

1. In the GraphQL Playground, click the Query Variables tab in the bottom left corner.
2. Create a variable called createCartInput that contains the line item in the cart. Note that what you input for the quantity and productEntityId will be different than what is shown below.

{
  "createCartInput":{
    "lineItems":[
      {
        "quantity":1,
        "productEntityId":81
      }
    ]
  }
}

3. Next, write a mutation that contains the variable.

mutation createCartSimple($createCartInput:CreateCartInput!)

4. Add the cart field and specify that we want to createCart based on the variable, and that you want the response to show the entityId, name, and quantity of the physical item added to the cart.

mutation createCartSimple($createCartInput:CreateCartInput!){
  cart{
    createCart(input:$createCartInput){
      cart{
        entityId
        lineItems{
          physicalItems{
            name
            quantity
          }
        }
      }
    }
  }
}

5. Click the Play button in the middle of the GraphQL Playground to run the query.
6. Observe the response.
7. View the storefront and observe that the item has been added to the cart.

When there is customer context for the GraphQL request that creates a cart (whether from a client-side session or a customer access token), the cart will be assigned to and accessible only by that customer.

Get a Cart

In this query, we will ask for the cart ID, currency, and line items. We will further ask for product pricing information and shipping requirements.

1. In the GraphQL playground, begin writing the query with the root, site field, and cart field. Specify next to the cart field that we want the entityId, currencyCode, and amount in the response.

query{
  site{
    cart{
      entityId
      currencyCode
      amount{
        value
      }
    }
  }
}

2. Next, let’s add lineItem information to the query. Specify that we want to know the entityId, sku, name, and quantity of the physicalItems in the cart.

query{
  site{
    cart{
      entityId
      currencyCode
      amount{
        value
      }
      lineItems{
        physicalItems{
          entityId
          sku
          name
          quantity
        }
      }
    }
  }
}

3. Click the Play button in the middle of the GraphQL Playground to run the query.
4. Observe the response.

Add Cart Line Item

In this mutation, we will add another physical item to the cart.

1. In the GraphQL Playground, click the Query Variables tab in the bottom left corner.
2. Create a variable called addCartLineItemsInput that contains the cartEntityId and lineItems that will be added to the cart. Note that what you input for the cartEntityId and productEntityId will be different than what is shown below.

{
  "addCartLineItemsInput":{
    "cartEntityId":"938f34af-986b-475e-a006-85a37116aeaf",
    "data":{
      "lineItems":[
        {
          "quantity":1,
          "productEntityId":111
        }
      ]
    }
  }
}

3. Write a mutation that contains the variable.

mutation addCartLineItems($addCartLineItemsInput: AddCartLineItemsInput!) {

4. Add the cart field and specify that we want to addCartLineItems based on the variable and want the response to show the cart entityId.

mutation addCartLineItems($addCartLineItemsInput:AddCartLineItemsInput!){
  cart{
    addCartLineItems(input:$addCartLineItemsInput){
      cart{
        entityId
      }
    }
  }
}

5. Click the Play button in the middle of the GraphQL Playground to run the query.
6. Observe the response.
7. View the storefront and observe that the new item has been added to the cart.

Create a Cart Redirect URL

In order to load the cart that was created in a headless storefront into the BigCommerce storefront’s own session, you will need to create a cart redirect URL. The steps below will walk you through creating a cart redirect URL with the GraphQL Storefront API. You have the option to create a redirect URL for embedded checkout and redirected checkout, but the example below only shows redirectedCheckoutURL.

Before completing the steps below, you will need the cartEntityId from the cart created in previous lab steps.

1. In the GraphQL Playground, click the Query Variables tab in the bottom left corner.
2. Create a variable called cartId that contains the cartEntityId of the cart you want to use for the redirect URL. Note that what you input for cartId will be different than what is shown below.

{
  "cartId": "a9061212-6fdd-46a5-a617-50e89a5e0fc2"
}

3. Next, write a mutation that contains the variable.

mutation CreateRedirectURL($cartId: String) {

4. Next, add the cart field and specify that we want to createCartRedirectUrls based on the variable and want the response to show the redirectedCheckoutUrl and embeddedCheckoutUrl.

mutation CreateRedirectURL($cartId: String) {
  cart {
    createCartRedirectUrls(input: {cartEntityId: $cartId}) {
      redirectUrls {
        redirectedCheckoutUrl
        embeddedCheckoutUrl
      }
    }
  }
}

5. Click the play button to submit the request.
6. View your response.

{
  "data": {
    "cart": {
      "createCartRedirectUrls": {
        "redirectUrls": {
          "redirectedCheckoutUrl": "https://petonline.us/cart.php?action=loadInCheckout&id=a9061212-6fdd-46a5-a617-50e89a5e0fc2&token=17c4cdfa6a4d175faff2cd0e674a2214d1676ac5b0749c6e193c12702c421db9",
          "embeddedCheckoutUrl": "https://petonline.us/cart.php?embedded=1&action=loadInCheckout&id=a9061212-6fdd-46a5-a617-50e89a5e0fc2&token=17c4cdfa6a4d175faff2cd0e674a2214d1676ac5b0749c6e193c12702c421db9"
        }
      }
    }
  }
}

Syncing a Customer Session

When a cart belongs to a registered customer, it’s important that the customer’s logged-in session be maintained when redirecting to checkout.

For client-side requests relying on the BigCommerce storefront session cookie, this is taken care of automatically, as the same session that establishes the customer context for the GraphQL requests is also responsible for their logged-in status in Stencil.

For server-side requests, as long as the appropriate customer access token is provided in the createCartRedirectUrls request, the redirect URL will automatically log the user into this customer session in addition to loading the cart.

Optional Step - Delete a Cart

In this mutation, you will delete a cart.

1. In the GraphQL Playground, click the Query Variables tab in the bottom left corner.
2. Create a variable called deleteCartInput that contains the entityId of the cart that will be deleted. Note that what you input for the cartEntityId and will be different than what is shown below.

{
  "deleteCartInput":{
    "cartEntityId":"938f34af-986b-475e-a006-85a37116aeaf"
  }
}

3. Write a mutation that contains the variable.

mutation deleteCart($deleteCartInput:DeleteCartInput!){

4. Add the cart field and specify that we want to deleteCart based on the variable and want the response to show the cart deletedCartEntityId.

mutation deleteCart($deleteCartInput:DeleteCartInput!){
  cart{
    deleteCart(input:$deleteCartInput){
      deletedCartEntityId
    }
  }
}

5. Click the Play button in the middle of the GraphQL Playground to run the query.
6. Observe the response.
7. View the storefront and observe that the cart is empty.

Get a Checkout

In this query, we will request checkout information such as the billing address, order ID, subtotal, grand total, and outstanding balance.

1. In the GraphQL playground, begin writing the query with the root, site field, and checkout field. Specify next to the checkout field that we want the entityId, billingAddress, orderId, subTotal, grandTotal, and outstandingBalance in the response.

query{
  site{
    checkout{
      entityId
      billingAddress{
        firstName
        lastName
        email
        address1
        city
        stateOrProvince
        stateOrProvinceCode
        countryCode
        postalCode
      }
      order{
        entityId
      }
      subtotal{
        value
      }
      grandTotal{
        value
      }
      outstandingBalance{
        value
      }
    }
  }
}

2. Click the Play button in the middle of the GraphQL Playground to run the query.
3. Observe the response.

Add Checkout Billing Address

In this mutation, we will add a billing address to the checkout we queried in the previous step.

1. In the GraphQL Playground, click the Query Variables tab in the bottom left corner.
2. Create a variable called addCheckoutBillingAddressInput that contains the billing address information to be added. Note that what you input for the checkoutEntityId and in the address fields will be different than what is shown below.

{
  "addCheckoutBillingAddressInput":{
    "checkoutEntityId":"938f34af-986b-475e-a006-85a37116aeaf",
    "data":{
      "address":{
        "firstName":"Josh",
        "lastName":"Smith",
        "email":"josh.smith@teststore.com",
        "company":"BigCommerce L+D",
        "address1":"11305 4 Points Drive",
        "city":"Austin",
        "stateOrProvince":"TX",
        "stateOrProvinceCode":"TX",
        "countryCode":"US",
        "postalCode":"78726",
        "phone":"5128654500",
        "shouldSaveAddress":false
      }
    }
  }
}

3. Next, write a mutation that contains the variable.

mutation addCheckoutBillingAddress($addCheckoutBillingAddressInput: AddCheckoutBillingAddressInput!) {

4. Next, add the checkout field and specify that we want to addCheckoutBillingAddress based on the variable and want the response to show the checkout entityId.

mutation addCheckoutBillingAddress($addCheckoutBillingAddressInput:AddCheckoutBillingAddressInput!){
  checkout{
    addCheckoutBillingAddress(input:$addCheckoutBillingAddressInput){
      checkout{
        entityId
      }
    }
  }
}

5. Click the Play button in the middle of the GraphQL Playground to run the query.
6. Observe the response.

Add Shipping Consignment to Checkout

In this mutation, we will add a shipping address to the checkout.

1. Before we can add a shipping consignment, we need to get the lineItem entityIds. In the GraphQL playground, begin writing the query with the root, site field, and cart field. Specify next to the cart field that we want the entityId for each lineItem in the response.

query{
  site{
    cart{
      lineItems{
        physicalItems{
          entityId
        }
      }
    }
  }
}

2. Create a variable called addCheckoutShippingConsignmentsInput that contains the checkout entityId, shipping address, entityId, and quantity for each lineItem. Note that what you input for the checkoutEntityId, address, and lineItems fields will be different than what is shown below. Additionally, you can add more or less lineItems to this variable if needed.

{
  "addCheckoutShippingConsignmentsInput": {
    "checkoutEntityId": "938f34af-986b-475e-a006-85a37116aeaf",
    "data": {
      "consignments": [
        {
          "address": {
            "firstName": "Josh",
            "lastName": "Smith",
            "email": "josh.smith@teststore.com",
            "company": "BigCommerce L+D",
            "address1": "11305 4 Points Drive",
            "city": "Austin",
            "stateOrProvince": "TX",
            "stateOrProvinceCode": "TX",
            "countryCode": "US",
            "postalCode": "78726",
            "phone": "5128654500",
            "shouldSaveAddress": false
          },
          "lineItems": [
            {
              "lineItemEntityId": "c1264697-47a6-408a-9970-523eec9a94ea",
              "quantity": 1
            },
            {
              "lineItemEntityId": "9b507120-9b13-4378-95dc-a31134ff8ea1",
              "quantity": 1
            }
          ]
        }
      ]
    }
  }
}

3. Next, write a mutation that contains the variable.

mutation addCheckoutShippingConsignments($addCheckoutShippingConsignmentsInput: AddCheckoutShippingConsignmentsInput!) {

4. Next, add the checkout field and specify that we want to addCheckoutShippingConsignments based on the variable and want the response to show the checkout entityId, shipping consignment entityId, available shipping options, and selected shipping option.

mutation addCheckoutShippingConsignments($addCheckoutShippingConsignmentsInput: AddCheckoutShippingConsignmentsInput!){
  checkout{
    addCheckoutShippingConsignments(input:$addCheckoutShippingConsignmentsInput){
      checkout{
        entityId
        shippingConsignments{
          entityId
          availableShippingOptions{
            entityId
            description
          }
          selectedShippingOption{
            entityId
          }
        }
      }
    }
  }
}

5. Click the Play button in the middle of the GraphQL Playground to run the query.
6. Observe the response.

Select Checkout Shipping Option

In this mutation, we will select a shipping option for the checkout.

1. Before we can select a shipping option, we need to find what shipping options are available. In the GraphQL playground, begin writing the query with the root, site field, checkout field, and shipping consignments field. Specify next to the shipping consignments field that we want the entityId, description, and type for each availableShippingOptions in the response.

query{
  site{
    checkout{
      shippingConsignments{
        availableShippingOptions{
          entityId
          description
          type
        }
      }
    }
  }
}

2. Create a variable called selectCheckoutShippingOptionInput that contains the checkout entityId, consignment entityId, and shipping option entityId.

{
    "selectCheckoutShippingOptionInput": {
      "checkoutEntityId": "938f34af-986b-475e-a006-85a37116aeaf",
      "consignmentEntityId": "64d15e8061fc7",
      "data": {
        "shippingOptionEntityId": "4dcbf24f457dd67d5f89bcf374e0bc9b"
      }
    }
  }

3. Next, write a mutation that contains the variable.

mutation selectCheckoutShippingOption($selectCheckoutShippingOptionInput: SelectCheckoutShippingOptionInput!) {

4. Next, add the checkout field and specify that we want to selectCheckoutShippingOption based on the variable and want the response to show the checkout entityId.

mutation selectCheckoutShippingOption($selectCheckoutShippingOptionInput:SelectCheckoutShippingOptionInput!){
  checkout{
    selectCheckoutShippingOption(input:$selectCheckoutShippingOptionInput){
      checkout{
        entityId
      }
    }
  }
}

5. Click the Play button in the middle of the GraphQL Playground to run the query.
6. Observe the response.

Complete Checkout

In this mutation, we will complete the checkout that we created in the previous steps.

1. Create a variable called completeCheckoutInput that contains the checkout entityId.

{
  "completeCheckoutInput":{
    "checkoutEntityId":"938f34af-986b-475e-a006-85a37116aeaf"
  }
}

2. Next, write a mutation that contains the variable.

mutation completeCheckout($completeCheckoutInput: CompleteCheckoutInput!) {

3. Next, add the checkout field and specify that we want to completeCheckout based on the variable and want the response to show the order entityId and payment access token.

mutation completeCheckout($completeCheckoutInput:CompleteCheckoutInput!){
  checkout{
    completeCheckout(input:$completeCheckoutInput){
      orderEntityId
      paymentAccessToken
    }
  }
}

4. Click the Play button in the middle of the GraphQL Playground to run the query.
5. Observe the response.