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
Argument | Type | Description | Required | Validation / Notes |
---|---|---|---|---|
input | CartInput! | The input for creating the cart. | Yes | Contains optional lines and buyerIdentity fields. |
CartInput Fields
Field | Type | Description | Required | Validation / Notes |
---|---|---|---|---|
lines | [CartLineInput] | A list of merchandise lines to add to the cart. | No | Each line includes merchandiseId and quantity. |
buyerIdentity | BuyerIdentityInput | The buyer identity associated with the cart. | No | Includes optional email and phone fields. |
Return Type
CartCreatePayload
The payload returned by the cartCreate
mutation contains:
Field | Type | Description | Required |
---|---|---|---|
cart | Cart! | The created cart object. | Yes |
userErrors | [UserError]! | List of errors that occurred during cart creation. | Yes |
Cart Fields (example subset)
Field | Type | Description |
---|---|---|
id | ID! | Unique identifier of the cart. |
lines | [CartLine]! | List of merchandise lines in the cart. |
buyerIdentity | BuyerIdentity | Buyer identity information associated with the cart. |
UserError Fields
Field | Type | Description |
---|---|---|
field | [String] | The input field(s) associated with the error. |
message | String | Description 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 itsid
, optionallines
, and optionalbuyerIdentity
.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 anylines
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.
Related Types
- CartInput: Input object containing optional
lines
andbuyerIdentity
. - CartLineInput: Input object for each merchandise line with
merchandiseId
andquantity
. - BuyerIdentityInput: Input object containing buyer contact fields such as
email
andphone
. - CartCreatePayload: Return type containing the created
cart
and anyuserErrors
. - 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