CartCreatePayload

Payload returned by the cartCreate mutation. This object contains the newly created cart and any errors that occurred during the cart creation process.

Type Definition

type CartCreatePayload {
  cart: Cart!
  userErrors: [UserError]!
}

Fields

Relationships

• cart: This field returns the newly created Cart object, representing the state of the cart immediately after creation.
• userErrors: This field returns a list of UserError objects describing any issues encountered during the cart creation mutation. Each error provides details useful for debugging or informing the user.

Usage Examples

Basic Query

mutation {
  cartCreate {
    cart {
      id
      createdAt
      lines(first: 5) {
        edges {
          node {
            id
            quantity
            merchandise {
              ... on ProductVariant {
                id
                title
                price
              }
            }
          }
        }
      }
    }
    userErrors {
      field
      message
    }
  }
}

Field Selection

mutation {
  cartCreate {
    cart {
      id
      checkoutUrl
      totalQuantity
    }
    userErrors {
      message
    }
  }
}

Nested Queries

mutation {
  cartCreate {
    cart {
      id
      lines(first: 3) {
        edges {
          node {
            id
            quantity
            merchandise {
              ... on ProductVariant {
                id
                title
                product {
                  id
                  title
                }
              }
            }
          }
        }
      }
    }
    userErrors {
      message
    }
  }
}

Filtering and Sorting

The CartCreatePayload type itself does not support filtering or sorting directly. However, you can apply filtering and sorting on related fields such as lines within the cart object, depending on the schema capabilities of the Cart type.

Example filtering cart lines by quantity greater than 1 (assuming the lines connection supports arguments):

mutation {
  cartCreate {
    cart {
      id
      lines(first: 5, query: "quantity:>1") {
        edges {
          node {
            id
            quantity
          }
        }
      }
    }
    userErrors {
      message
    }
  }
}

Note: Confirm support for filtering arguments on lines in the Cart type schema.

Implements

The CartCreatePayload type does not implement any interfaces.

Connections

The cart field returns a Cart object, which may include connections such as lines representing the items in the cart. These connections support pagination and nested queries.

Related Types

• Cart: Represents the shopping cart object created by this mutation.
• UserError: Represents errors encountered during the mutation, detailing the field and message for each error.

Best Practices

• Always check the userErrors field after performing the cartCreate mutation to handle any issues gracefully.
• Use pagination when querying nested connections like lines to optimize performance.
• Select only the fields you need from the cart to minimize response size and improve query efficiency.
• Use nested queries to retrieve related product or variant information for cart lines in a single request.

Notes

• The API currently requires no authentication for the cartCreate mutation, but this behavior may change in future versions.
• The cart field is guaranteed to be non-null on successful creation; however, always verify userErrors to detect partial failures or validation issues.
• Use caching strategies on client-side to store cart state and reduce redundant network requests.
• Be mindful of query complexity when nesting multiple levels of related objects to maintain optimal performance.