Crystallize logo

Update Cart

Now that we have covered how to get the auth token and hydrate the cart with the Shop API, there are actions a user will perform such as adding item to a cart or removing an existing item from the cart. Let’s take a look at the different mutations available to take care of such actions.

note

Mutating an item opts it out of management

addExternalItem creates items as external, and setCartItem and changeCartItemPricing flag an existing item as unmanaged — so the values you pass are preserved and later hydrations won't overwrite them with Catalog data. addCartItem and removeCartItem change only the quantity and keep an item's existing managed or external status.

addSkuItem

Add an item that already exists in Crystallize, referenced by its SKU. Crystallize fetches the item's data from the Catalog and keeps it managed. If the SKU is already in the cart as an unmanaged item, only its quantity is updated. The mutation takes the following arguments:

  • id: Cart ID
  • input
    • sku: SKU of the item in Crystallize
    • quantity: amount to increase the item count by (defaults to 1 if not provided)
    • Optionally, meta (key/value pairs) and taxRate to override the tax rate used in price calculation.
mutation addSkuItem {
    addSkuItem(id: "CART_ID", input: {sku: "hammer-mjolnir"}) {
	    id
    }
}

addExternalItem

Add a fully custom (external) item that does not exist in Crystallize. You supply all of its details, and the item is stored as unmanaged. It takes the following arguments:

  • id: Cart ID
  • input
    • sku: SKU of the external item
    • quantity: amount to increase the item count by (defaults to 1 if not provided)
    • name: name of the external item
    • variant: the variant's unit price (net, gross, and optional discounts) and product information such as its ID and path
  • It also accepts images and meta information.
mutation addExternalItem {
	addExternalItem(id: "CART_ID", input: {
		sku: "hammer-mjolnir"
		name: "Mjolnir"
		variant: {
			price: {
				net: 500.00
				gross: 550.00
			}
			product: {
				id: "4389955"
				path: "/products/hammer/mjolnir"
			}
		}
	}) {
		id
	}
}

setCartItem

Add or update any item, whether or not it exists in Crystallize, and flag it as unmanaged. Unlike addSkuItem, which fetches data from Crystallize based on the SKU, setCartItem stores exactly the values you provide. It takes the same input as addExternalItem:

  • id: Cart ID
  • input
    • sku: SKU of the item
    • quantity: amount to increase the item count by (defaults to 1 if not provided)
    • name: name of the item
    • variant: the variant's unit price (net, gross, and optional discounts) and product information such as its ID and path
  • It also accepts images and meta information.
mutation setCartItem {
	setCartItem(id: "CART_ID", input: {
		sku: "hammer-mjolnir"
		name: "Mjolnir"
		variant: {
			price: {
				net: 500.00
				gross: 550.00
			}
			product: {
				id: "4389955"
				path: "/products/hammer/mjolnir"
			}
		}
	}) {
		id
	}
}

addCartItem

Increase the quantity of an item that is already in the cart, identified by its SKU. To add an item that is not yet in the cart, use addSkuItem or addExternalItem instead. This mutation does not change the item's managed or external status. It takes the following arguments:

  • id: Cart ID
  • sku: SKU of the item
  • quantity: amount to increase the item count by (defaults to 1 if not provided)
mutation addCartItem {
	addCartItem(id: "CART_ID", sku: "hammer-mjolnir", quantity: 2){
		id
	}
}

removeCartItem

Decrease the quantity of an item, or remove it entirely when the quantity reaches zero. Like addCartItem, this does not change the item's managed or external status. Required arguments include:

  • id: Cart ID
  • sku: SKU of the item
  • quantity: amount to decrease the item count by (defaults to 1 if not provided)
mutation removeCartItem {
	removeCartItem(id: "CART_ID", sku: "hammer-mjolnir", quantity: 2){
		id	
	}
}

changeCartItemPricing

Change the price and/or quantity of an item already in the cart. This mutation also flags the item as unmanaged, so its details are no longer fetched from Crystallize. Input arguments include:

  • id: Cart ID
  • input
    • sku: SKU of the item
    • price: net and gross, plus discounts if applicable (optional)
    • quantity: the new quantity for the item (optional)
mutation changeCartItemPricing {
	changeCartItemPricing(id: "CART_ID", input: {
		sku: "hammer-mjolnir"
		quantity: 2
		price: {
			net: 500.00
			gross: 550.00
		}
	}){
		id
	}
}

setCustomer

You most likely have a customer associated with each cart. You can attach the customer to a cart using this mutation, which accepts the following:

  • id: Cart ID
  • isGuest: whether the customer is a guest (true) or a registered customer (false)
  • identifier: unique customer identifier (email in this example)
  • Other personal information such as first name, last name, middle name, phone number, email, birth date, company name, tax number, etc.
  • addresses: one address object or an array of addresses; each address has a type (delivery, billing, or other)
  • Additionally, you can set meta information and external references on the customer.
mutation setCustomer {
	setCustomer(id: "CART_ID", input: {
		isGuest: false 
		identifier: "legolas@gmail.com" 
		firstName: "Legolas" 
		lastName: "Greenleaf" 
		phone: "12345678" 
		email: "legolas@gmail.com"
		addresses: { 
			type: delivery 
			streetNumber: "16" 
			street: "Greenwood" 
			city: "Woodland Realm" 
			country: "Ithilien" 
			postalCode: "1408" 
		}
	}){
		id
	}
}

setMeta

Lastly, to set meta information on the cart as a whole, use the setMeta mutation. Input arguments include:

  • id: Cart ID
  • meta: an array of key/value pairs
  • merge: when true (the default), the provided pairs are merged into the existing meta; when false, they replace all cart meta
mutation setMeta {
	setMeta(id: "CART_ID", meta: [{
		key: "Paid via"
		value: "invoice"
	}]) {
		id
	}
}