Add an item to a guest cart
const url = 'https://apibase.ecomweb.app/api/v1/public/stores/example/cart/items';const options = { method: 'POST', headers: { 'x-storefront-api-key': '<x-storefront-api-key>', 'Content-Type': 'application/json' }, body: '{"product_id":1,"variant_id":12,"quantity":1}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://apibase.ecomweb.app/api/v1/public/stores/example/cart/items \ --header 'Content-Type: application/json' \ --header 'x-storefront-api-key: <x-storefront-api-key>' \ --data '{ "product_id": 1, "variant_id": 12, "quantity": 1 }'Adds a product variant to the guest cart for the x-session-id header and creates the cart when there is none. Adding a product and variant that is already in the cart raises that line’s quantity by the amount sent. Prices are not stored here: read the cart to get priced lines. The body is not validated up front: a missing or invalid product_id fails with a server error rather than a 400.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”The store’s ref, as returned by GET /stores.
Header Parameters
Section titled “Header Parameters”An ID that identifies the visitor’s guest cart. Generate a random value (a UUID works) the first time, keep it in the browser and send it on every guest cart request. Without it, requests are not tied to a cart.
Request Bodyrequired
Section titled “Request Bodyrequired”object
ID of the product to add.
Example
1ID of the variant to add. Every purchasable product has at least one variant, so send it; the cart keeps the line without it, but checkout needs it.
Example
12Units to add. Defaults to 1. Adding a product and variant that is already in the cart increases that line’s quantity.
Example
2Responses
Section titled “Responses”object
ID of the cart the line was added to. A cart is created when the shopper has none.
The line, with its quantity after the change.
object
Cart line ID.
ID of the cart the line belongs to.
ID of the product.
ID of the variant, or null when the line has none.
Units in the line.
When the line was added, as an ISO 8601 timestamp.
When the line last changed, as an ISO 8601 timestamp.
Example generated
{ "cart_id": "example", "item": { "id": "example", "cart_id": "example", "product_id": 1, "variant_id": 1, "quantity": 1, "created_at": "example", "updated_at": "example" }}The key is missing, invalid, revoked or expired.
object
The HTTP status code.
What went wrong; validation failures list one message per problem.
The HTTP status text, such as Bad Request.
object
A stable, machine-readable error code.
A human-readable explanation.
Extra context about the error, when there is any.
object
When the error happened, as an ISO 8601 timestamp.
Example generated
{ "statusCode": 1, "message": [ "example" ], "error": "example"}The key may not do this: a missing scope, a readonly key, a publishable key on a Store API route, or a disallowed origin.
object
The HTTP status code.
What went wrong; validation failures list one message per problem.
The HTTP status text, such as Bad Request.
object
A stable, machine-readable error code.
A human-readable explanation.
Extra context about the error, when there is any.
object
When the error happened, as an ISO 8601 timestamp.
Example generated
{ "statusCode": 1, "message": [ "example" ], "error": "example"}