Cart
Introduction
The cart api is a streamlined abstraction of the Shopify Storefront API, allowing you to manage carts and handle checkout processes directly from within your website.
By default your store will make use of the Livewire cart that comes batteries included, but we understand there may be cases where users wish to use a direct API approach.
Key Features
- Cart Creation and Management: Create, retrieve, and manage shopping carts.
- Product Management: Add, update, or remove products in the cart.
- Discount Handling: Apply and manage discount codes.
- Buyer Identity: Manage buyer information for checkout.
- Checkout Integration: Generate checkout URLs.
Using the cart API
All cart management routes are protected by the CartManagement middleware, which ensures a cart exists before processing any request.
Create an empty cart
Creates a new empty cart.
POST /!/gaia/cart/create/empty
fetch('/!/gaia/cart/create/empty', {
method: 'POST'
});
Create a cart with a product
Creates a new cart with a specified product.
POST /!/gaia/cart/create
fetch('/!/gaia/cart/create', {
method: 'POST',
body: JSON.stringify({
product_id: '12345',
quantity: 2
}),
});
Parameters
-
product_id: (string) The ID of the product. -
quantity: (integer) The quantity of the product to add.
Get cart contents
Retrieves the current contents of the cart.
GET /!/gaia/cart/get
fetch('/!/gaia/cart/get');
Adding to cart
Adds a single product to the cart.
POST /!/gaia/cart/add
fetch('/!/gaia/cart/add', {
method: 'POST',
body: JSON.stringify({
product_id: '12345',
quantity: 2
}),
});
Parameters
-
product_id: (string) The ID of the product to add. -
quantity: (integer) The quantity of the product to add.
Updating a cart line
Updates the quantity of a product already in the cart.
POST /!/gaia/cart/update
fetch('/!/gaia/cart/update', {
method: 'POST',
body: JSON.stringify({
product_id: '12345',
quantity: 2
}),
});
Parameters
-
product_id: (string) The ID of the product to update. -
quantity: (integer) The new quantity for the product.
Remove from cart
Removes specified products from the cart.
DELETE /!/gaia/cart/remove
fetch('/!/gaia/cart/remove', {
method: 'DELETE',
body: JSON.stringify({
product_ids: [1939821, 9028312]
}),
});
Parameters
-
product_ids: (array, required) List of product IDs to remove (maximum of 250 items).
Delete cart
Deletes the entire cart.
DELETE /!/gaia/cart/delete
fetch('/!/gaia/cart/delete', {
method: 'DELETE'
});
Get checkout URL
Retrieves the checkout URL for the current cart.
GET /!/gaia/cart/checkout/url
fetch('/!/gaia/cart/checkout/url', {
method: 'GET'
});
Applying discount codes
Applies discount codes to the cart.
POST /!/gaia/cart/discount
fetch('/!/gaia/cart/discount', {
method: 'POST',
body: JSON.stringify({
discount_codes: [12332, 287312, 897213812]
}),
});
Required Parameters:
-
discount_codes: (array) List of discount codes to apply.
Update cart attributes
Updates specific attributes of the cart.
POST /!/gaia/cart/attribute
fetch('/!/gaia/cart/attribute', {
method: 'POST',
body: JSON.stringify({
key: 'some_attribute',
value: 'new_value'
}),
});
Required Parameters:
-
key: (string) The attribute key to update. -
value: (string) The new value for the attribute.
Cart note
Adds or updates a note on the cart.
POST /!/gaia/cart/note
fetch('/!/gaia/cart/note', {
method: 'POST',
body: JSON.stringify({
note: 'This is a cart note'
}),
});
Required Parameters:
-
note: (string) The note content.
Buyer identity
Updates the buyer's identity information.
POST /!/gaia/cart/update/identity
fetch('/!/gaia/cart/update/identity', {
method: 'POST',
body: JSON.stringify({
email: '[email protected]'
}),
});
Required Parameters:
-
email: (string) The attribute key to update.
Error handling
The API uses standard HTTP status codes for error responses:
-
404: Cart not found. -
500: Server error.
Error responses will include a JSON object with an error key containing a descriptive message.
Limitations
- The API operates within the limitations of the Shopify Storefront API.
- Some operations may require additional authentication or permissions based on your Shopify configuration.
Additional
For more detailed information on specific methods or advanced usage, please refer to the CartRepositoryInterface class implementation.