> This page is for Developer.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.bigcommerce.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.bigcommerce.com/_mcp/server.

# Lab - Query Practice

Plan: Developer Foundations

Lesson 22 of 28 · 45 min

### 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

> **Info**
>
> The cart created in this lab activity will be maintained across requests because of the storefront session cookie used in the GraphQL Playground environment.

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

```json showLineNumbers={false}
{
  "createCartInput":{
    "lineItems":[
      {
        "quantity":1,
        "productEntityId":81
      }
    ]
  }
}
```

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

```graphql showLineNumbers={false}
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.

```graphql showLineNumbers={false}
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.

```graphql showLineNumbers={false}
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.

```graphql showLineNumbers={false}
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.**

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

3. **Write** a mutation that contains the variable.

```graphql showLineNumbers={false}
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`.

```graphql showLineNumbers={false}
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.**

```json showLineNumbers={false}
{
  "cartId": "a9061212-6fdd-46a5-a617-50e89a5e0fc2"
}
```

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

```graphql showLineNumbers={false}
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.

```graphql showLineNumbers={false}
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.

```json showLineNumbers={false}
{
  "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.

> **Info**
>
> This step is **optional** because the next lab activity (Get Checkout) uses the information from the cart you created in the previous steps.

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.

```json showLineNumbers={false}
{
  "deleteCartInput":{
    "cartEntityId":"938f34af-986b-475e-a006-85a37116aeaf"
  }
}
```

3. **Write** a mutation that contains the variable.

```graphql showLineNumbers={false}
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`.

```graphql showLineNumbers={false}
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.

> **Info**
>
> If you completed the optional step above and deleted the cart, you will need to create a new cart. Go back to the beginning of this lab and follow the steps to create a new cart.

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.

```graphql showLineNumbers={false}
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.

```json showLineNumbers={false}
{
  "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.

```graphql showLineNumbers={false}
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`.

```graphql showLineNumbers={false}
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` `entityId`s. 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.

```graphql showLineNumbers={false}
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.

```json showLineNumbers={false}
{
  "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.

```graphql showLineNumbers={false}
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.

```graphql showLineNumbers={false}
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.

```graphql showLineNumbers={false}
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*.

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

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

```graphql showLineNumbers={false}
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`.

```graphql showLineNumbers={false}
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`.

```json showLineNumbers={false}
{
  "completeCheckoutInput":{
    "checkoutEntityId":"938f34af-986b-475e-a006-85a37116aeaf"
  }
}
```

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

```graphql showLineNumbers={false}
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.

```graphql showLineNumbers={false}
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.