cart

Retrieve the current shopping cart by its unique identifier. This query returns detailed information about the cart, including items, pricing, discounts, shipping, payment methods, and customer details.

Query Structure


query {
  cart(id: String!) {
    id
    createdAt
    customer {
      id
      email
      firstName
      lastName
    }
    discounts {
      code
      amount
      description
    }
    tags
    subtotalPrice
    totalPrice
    currency
    totalNetPrice
    totalTax
    taxLines {
      title
      rate
      price
    }
    customerNote
    paymentMethods {
      name
      type
      fee
    }
    paymentFee
    shippingMethods {
      name
      price
      estimatedDelivery
    }
    shippingPrice
    lines {
      id
      productId
      quantity
      title
      price
    }
    physicalLines {
      id
      productId
      quantity
      title
      price
    }
    lineCount
    shippingAddress {
      firstName
      lastName
      address1
      address2
      city
      province
      country
      zip
      phone
    }
    billingAddress {
      firstName
      lastName
      address1
      address2
      city
      province
      country
      zip
      phone
    }
    checkoutUrl
  }
}

Arguments

Argument	Type	Description	Required	Default Value
id	String	The ID of the cart to retrieve.	Yes	N/A

Return Type

Cart

Represents a shopping cart in the store with detailed information including totals, items, discounts, shipping, payment, and customer data.

Field	Type	Description
id	String	The unique identifier for this cart.
createdAt	String	Date when this cart was created (RFC 2822 format).
customer	Customer	Customer linked to this cart, if any.
discounts	[CartDiscount]	Discounts applied to this cart.
tags	[String]	Tags associated with this cart.
subtotalPrice	Float	Subtotal price in the customer’s currency.
totalPrice	Float	Total price in the customer’s currency.
currency	String	Currency code for this cart.
totalNetPrice	Float	Net total price in the customer’s currency.
totalTax	Float	Total tax amount in the customer’s currency.
taxLines	[CartTaxLine]	Tax lines applied to this cart.
customerNote	String	Customer note attached to the cart.
paymentMethods	[CartPaymentMethod]	Payment methods available or used for this cart.
paymentFee	Float	Total payment fee in the customer’s currency.
shippingMethods	[CartShippingMethod]	Shipping methods selected for this cart.
shippingPrice	Float	Total shipping cost in the customer’s currency.
lines	[CartLineItem]	All items in this cart.
physicalLines	[CartLineItem]	Physical items in this cart.
lineCount	Int	Number of items in this cart.
shippingAddress	Address	Shipping address associated with this cart.
billingAddress	Address	Billing address associated with this cart.
checkoutUrl	String	URL to proceed to checkout for this cart.

Examples

Basic Query


query {
  cart(id: "eyJhbGciOiJIUzI1NiJ9...") {
    id
    totalPrice
    currency
    lineCount
  }
}

Advanced Query


query {
  cart(id: "eyJhbGciOiJIUzI1NiJ9...") {
    id
    createdAt
    customer {
      id
      email
      firstName
      lastName
    }
    discounts {
      code
      amount
      description
    }
    subtotalPrice
    totalPrice
    totalTax
    taxLines {
      title
      rate
      price
    }
    paymentMethods {
      name
      type
      fee
    }
    shippingMethods {
      name
      price
      estimatedDelivery
    }
    lines {
      id
      productId
      quantity
      title
      price
    }
    shippingAddress {
      firstName
      lastName
      address1
      city
      country
      zip
      phone
    }
    billingAddress {
      firstName
      lastName
      address1
      city
      country
      zip
      phone
    }
    checkoutUrl
  }
}

Field Selection


query {
  cart(id: "eyJhbGciOiJIUzI1NiJ9...") {
    lineCount
    lines {
      productId
      quantity
      price
    }
    discounts {
      code
      amount
    }
    shippingPrice
    paymentFee
    totalPrice
  }
}

cURL Example


curl -X POST https://www.mystoreurl.com/graphql/0.8.0/ \
  -H "Content-Type: application/json" \
  -d '{"query":"query ($id: String!) { cart(id: $id) { id totalPrice currency lineCount } }","variables":{"id":"eyJhbGciOiJIUzI1NiJ9..."}}'

JavaScript Example


async function fetchCart(cartId) {
  const query = `
    query ($id: String!) {
      cart(id: $id) {
        id
        totalPrice
        currency
        lineCount
      }
    }
  `;
 
  const variables = { id: cartId };
 
  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 null;
    }
 
    return data.cart;
  } catch (error) {
    console.error('Network error:', error);
    return null;
  }
}
 
// Usage example
fetchCart("eyJhbGciOiJIUzI1NiJ9...").then(cart => {
  if (cart) {
    console.log('Cart total price:', cart.totalPrice);
  } else {
    console.log('Failed to fetch cart.');
  }
});

Response Format

The response contains a cart object with the fields requested in the query. Example response for a basic query:


{
  "data": {
    "cart": {
      "id": "eyJhbGciOiJIUzI1NiJ9...",
      "totalPrice": 150.75,
      "currency": "USD",
      "lineCount": 3
    }
  }
}

For errors, the response includes an errors array with details.

Error Handling

Error Code	Description	Possible Cause	Recommended Action
`BAD_USER_INPUT`	Invalid or missing argument value.	Missing or malformed `id` argument.	Verify and provide a valid cart ID.
`NOT_FOUND`	Cart with the specified ID does not exist.	Cart ID is incorrect or expired.	Confirm the cart ID is correct.
`INTERNAL_SERVER_ERROR`	Unexpected server error.	Server-side issue.	Retry later or contact support.
`RATE_LIMIT_EXCEEDED`	Too many requests in a short time.	Exceeded API rate limits.	Implement retry with backoff.

Clients should always check for the presence of an errors array in the response and handle errors gracefully.

Performance Considerations

Pagination: Since the cart query returns all lines and related data, avoid requesting unnecessary fields to reduce payload size.
Caching: Cart data is dynamic; avoid aggressive caching. Cache only static data like product details separately.
Rate Limiting: Respect API rate limits to avoid RATE_LIMIT_EXCEEDED errors. Implement exponential backoff on retries.
Field Selection: Request only the fields needed to optimize response times and bandwidth.
Complex Queries: Avoid requesting deeply nested fields unless necessary, as this can increase response time.

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.

Customer

Represents a customer linked to the cart.

Field	Type	Description
id	String	Unique customer ID.
email	String	Customer email address.
firstName	String	Customer first name.
lastName	String	Customer last name.

CartDiscount

Represents a discount applied to the cart.

Field	Type	Description
code	String	Discount code applied.
amount	Float	Discount amount.
description	String	Description of the discount.

CartTaxLine

Represents a tax line applied to the cart.

Field	Type	Description
title	String	Tax line title or name.
rate	Float	Tax rate applied.
price	Float	Tax amount for this line.

CartPaymentMethod

Represents a payment method for the cart.

Field	Type	Description
name	String	Name of the payment method.
type	String	Type/category of payment.
fee	Float	Payment fee amount.

CartShippingMethod

Represents a shipping method for the cart.

Field	Type	Description
name	String	Name of the shipping method.
price	Float	Shipping cost.
estimatedDelivery	String	Estimated delivery timeframe.

CartLineItem

Represents an item in the cart.

Field	Type	Description
id	String	Unique line item ID.
productId	Int	Product identifier.
quantity	Int	Quantity of the product.
title	String	Product title or name.
price	Float	Price per unit of the product.

Address

Represents a postal address.

Field	Type	Description
firstName	String	Recipient’s first name.
lastName	String	Recipient’s last name.
address1	String	Primary street address.
address2	String	Secondary street address.
city	String	City name.
province	String	State or province.
country	String	Country name.
zip	String	Postal or ZIP code.
phone	String	Contact phone number.

Notes

The cart query requires the cart id argument, which is typically a JWT token representing the cart session.
The checkoutUrl field provides a direct link to complete the purchase.
Physical and non-physical items can be differentiated using the physicalLines and lines fields.
Always validate the cart ID before querying to avoid errors.
The API is designed to be flexible and extensible; request only the fields you need for optimal performance.