Skip to Content
ReferenceStorefrontv0.8.0 API ReferenceMutationscartCreate

cartCreate

Creates a new cart.

Mutation Structure

mutation cartCreate($input: CartInput!) {
  cartCreate(input: $input) {
    cart {
      id
      lines {
        id
        merchandiseId
        quantity
      }
      buyerIdentity {
        email
        phone
      }
    }
    userErrors {
      field
      message
    }
  }
}

Input Arguments

ArgumentTypeDescriptionRequiredValidation / Notes
inputCartInput!The input for creating the cart.YesContains optional lines and buyerIdentity fields.

CartInput Fields

FieldTypeDescriptionRequiredValidation / Notes
lines[CartLineInput]A list of merchandise lines to add to the cart.NoEach line includes merchandiseId and quantity.
buyerIdentityBuyerIdentityInputThe buyer identity associated with the cart.NoIncludes optional email and phone fields.

Return Type

CartCreatePayload

The payload returned by the cartCreate mutation contains:

FieldTypeDescriptionRequired
cartCart!The created cart object.Yes
userErrors[UserError]!List of errors that occurred during cart creation.Yes

Cart Fields (example subset)

FieldTypeDescription
idID!Unique identifier of the cart.
lines[CartLine]!List of merchandise lines in the cart.
buyerIdentityBuyerIdentityBuyer identity information associated with the cart.

UserError Fields

FieldTypeDescription
field[String]The input field(s) associated with the error.
messageStringDescription of the error.

Examples

Basic Mutation

mutation {
  cartCreate(input: {}) {
    cart {
      id
    }
    userErrors {
      field
      message
    }
  }
}

Advanced Mutation

mutation {
  cartCreate(input: {
    lines: [
      {
        merchandiseId: 12345,
        quantity: 2
      },
      {
        merchandiseId: 67890,
        quantity: 1
      }
    ],
    buyerIdentity: {
      email: "buyer@example.com",
      phone: "+1234567890"
    }
  }) {
    cart {
      id
      lines {
        id
        merchandiseId
        quantity
      }
      buyerIdentity {
        email
        phone
      }
    }
    userErrors {
      field
      message
    }
  }
}

Input Validation

mutation {
  cartCreate(input: {
    lines: [
      {
        merchandiseId: 12345,
        quantity: 0
      }
    ]
  }) {
    cart {
      id
    }
    userErrors {
      field
      message
    }
  }
}

cURL Example

curl -X POST https://www.mystoreurl.com/graphql/0.8.0 \
  -H "Content-Type: application/json" \
  -d '{"query":"mutation cartCreate($input: CartInput!) { cartCreate(input: $input) { cart { id lines { id merchandiseId quantity } buyerIdentity { email phone } } userErrors { field message } } }","variables":{"input":{"lines":[{"merchandiseId":12345,"quantity":2}],"buyerIdentity":{"email":"buyer@example.com","phone":"+1234567890"}}}}'

JavaScript Example

async function createCart() {
  const query = `
    mutation cartCreate($input: CartInput!) {
      cartCreate(input: $input) {
        cart {
          id
          lines {
            id
            merchandiseId
            quantity
          }
          buyerIdentity {
            email
            phone
          }
        }
        userErrors {
          field
          message
        }
      }
    }
  `;
 
  const variables = {
    input: {
      lines: [
        { merchandiseId: 12345, quantity: 2 },
        { merchandiseId: 67890, quantity: 1 }
      ],
      buyerIdentity: {
        email: "buyer@example.com",
        phone: "+1234567890"
      }
    }
  };
 
  try {
    const response = await fetch("https://www.mystoreurl.com/graphql/0.8.0", {
      method: "POST",
      headers: {
        "Content-Type": "application/json"
      },
      body: JSON.stringify({ query, variables })
    });
 
    const { data, errors } = await response.json();
 
    if (errors) {
      console.error("GraphQL errors:", errors);
      return;
    }
 
    if (data.cartCreate.userErrors.length) {
      console.error("User errors:", data.cartCreate.userErrors);
      return;
    }
 
    console.log("Created cart:", data.cartCreate.cart);
  } catch (error) {
    console.error("Network or fetch error:", error);
  }
}

Response Format

The response contains the cartCreate payload with two main fields:

  • cart: The newly created cart object, including its id, optional lines, and optional buyerIdentity.
  • userErrors: An array of errors encountered during cart creation. If empty, the operation was successful.

Example successful response:

{
  "data": {
    "cartCreate": {
      "cart": {
        "id": "abc123",
        "lines": [
          {
            "id": "line1",
            "merchandiseId": 12345,
            "quantity": 2
          }
        ],
        "buyerIdentity": {
          "email": "buyer@example.com",
          "phone": "+1234567890"
        }
      },
      "userErrors": []
    }
  }
}

Example response with validation errors:

{
  "data": {
    "cartCreate": {
      "cart": null,
      "userErrors": [
        {
          "field": ["lines", "0", "quantity"],
          "message": "Quantity must be at least 1."
        }
      ]
    }
  }
}

Error Handling

Common error scenarios include:

  • Validation errors: For example, providing a quantity less than 1 in any lines entry will result in a user error.
  • Invalid merchandiseId: If a merchandiseId does not exist or is invalid, an error will be returned.
  • Malformed input: Missing required fields or invalid types will cause errors.

Example user error:

{
  "field": ["lines", "0", "quantity"],
  "message": "Quantity must be at least 1."
}

Clients should always check the userErrors array to handle errors gracefully.

Authentication

This API currently does not require authentication. However, authentication requirements may be introduced in future versions. Monitor API updates for any changes to authentication requirements.

Side Effects

  • Creates a new cart resource in the system.
  • Adding lines during creation reserves the merchandise in the cart.
  • Buyer identity information is associated with the cart for personalization or checkout purposes.
  • No payment or order is created at this stage.

Authentication

No authentication is required to call this mutation at present.

  • CartInput: Input object containing optional lines and buyerIdentity.
  • CartLineInput: Input object for each merchandise line with merchandiseId and quantity.
  • BuyerIdentityInput: Input object containing buyer contact fields such as email and phone.
  • CartCreatePayload: Return type containing the created cart and any userErrors.
  • UserError: Object describing errors related to input validation or processing.

Notes

  • The mutation supports adding multiple merchandise lines at cart creation.
  • Quantity values must be positive integers.
  • Buyer identity fields are optional but recommended for a better user experience.
  • The API may enforce rate limiting; clients should implement retry logic with backoff.
  • Always inspect userErrors to detect and handle input issues.
  • Use GraphQL variables to improve query readability and reusability.
Last updated on
cartBuyerIdentityUpdatecartDiscountCodesUpdate