CartLinesAddPayload

Payload returned by the cartLinesAdd mutation. This object contains the updated cart after adding lines, along with any user errors that occurred during the operation.

Type Definition

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

Fields

Relationships

• cart: This field returns the updated Cart object reflecting the current state after lines have been added. It allows clients to access all cart details such as items, totals, and other cart-specific information.
• userErrors: This field returns a list of UserError objects describing any issues encountered during the addition of lines to the cart. This helps clients handle validation or business logic errors gracefully.

Usage Examples

Basic Query

mutation {
  cartLinesAdd(cartId: "eyJhbGciOiJIUzI1NiJ9...", lines: [{ merchandiseId: 12345, quantity: 2 }]) {
    cart {
      id
      totalQuantity
    }
    userErrors {
      field
      message
    }
  }
}

Field Selection

mutation {
  cartLinesAdd(cartId: "eyJhbGciOiJIUzI1NiJ9...", lines: [{ merchandiseId: 67890, quantity: 1 }]) {
    cart {
      id
      createdAt
      updatedAt
      totalQuantity
      cost {
        subtotalAmount {
          amount
          currencyCode
        }
      }
    }
    userErrors {
      field
      message
    }
  }
}

Nested Queries

mutation {
  cartLinesAdd(cartId: "eyJhbGciOiJIUzI1NiJ9...", lines: [{ merchandiseId: 54321, quantity: 3 }]) {
    cart {
      id
      lines(first: 5) {
        edges {
          node {
            id
            quantity
            merchandise {
              id
              title
              price {
                amount
                currencyCode
              }
            }
          }
        }
      }
    }
    userErrors {
      field
      message
    }
  }
}

Filtering and Sorting

The CartLinesAddPayload type itself does not support filtering or sorting directly. However, the nested cart.lines connection can be queried with arguments such as first, last, after, and before to paginate through cart lines.

Example paginating cart lines after adding:

mutation {
  cartLinesAdd(cartId: "eyJhbGciOiJIUzI1NiJ9...", lines: [{ merchandiseId: 98765, quantity: 2 }]) {
    cart {
      id
      lines(first: 10, after: "cursor123") {
        edges {
          cursor
          node {
            id
            quantity
          }
        }
        pageInfo {
          hasNextPage
          hasPreviousPage
        }
      }
    }
    userErrors {
      field
      message
    }
  }
}

Implements

This type does not implement any interfaces.

Connections

• The cart field connects to the Cart object type, which contains further connections such as lines representing individual cart items.
• The userErrors field is a list of UserError objects, providing detailed error information.

Related Types

• Cart: Represents the shopping cart with details such as lines, totals, and metadata.
• UserError: Represents an error related to user input or business logic, containing fields like field and message.

Best Practices

• Always check the userErrors field after performing the cartLinesAdd mutation to handle any validation or business logic errors gracefully.
• Use pagination arguments on nested connections like cart.lines to efficiently manage large carts.
• Select only the fields you need from the cart object to optimize query performance.
• Handle errors in your client application by inspecting the field and message in userErrors.

Notes

• The cartLinesAdd mutation and its payload currently require no authentication, but this may change in future API versions.
• The cart field in the payload reflects the cart state immediately after the addition operation, ensuring clients have the latest data.
• The userErrors list will be empty if the operation completes successfully without issues.
• For performance, avoid requesting deeply nested fields unless necessary, especially on large carts.
• Use the JWT cart token format for cartId to securely identify carts in mutations.