Cart

Carts are temporary shopping sessions that hold items before checkout. Each cart tracks line items with snapshotted prices, computes totals automatically, and supports multi-currency conversion. Carts expire after 7 days of inactivity.

Base URL: https://api.hydrajs.dev

Auth: All cart endpoints accept publishable keys (pk_live_* or pk_test_*) – designed for client-side storefront use.

Endpoints

Method	Path	Auth	Description
POST	/v1/cart	Publishable	Create an empty cart
GET	/v1/cart/{id}	Publishable	Get a cart
POST	/v1/cart/{id}/items	Publishable	Add item to cart
PATCH	/v1/cart/{id}/items/{item_id}	Publishable	Update item quantity
DELETE	/v1/cart/{id}/items/{item_id}	Publishable	Remove item from cart
DELETE	/v1/cart/{id}	Publishable	Clear all items from cart

---

Create a cart

POST /v1/cart

Creates an empty cart. The cart inherits the project’s base currency. Returns the cart with 201.

Request

curl -X POST https://api.hydrajs.dev/v1/cart \
  -H "Authorization: Bearer pk_live_YOUR_KEY"

Response 201

{
	"data": {
		"id": "cart_abc123",
		"currency": "USD",
		"items": [],
		"item_count": 0,
		"subtotal": 0,
		"created_at": "2026-08-17T10:00:00Z",
		"updated_at": "2026-08-17T10:00:00Z"
	}
}

---

Get a cart

GET /v1/cart/{id}

Returns a cart with all its items, computed totals, and item count. Supports multi-currency conversion via the currency query parameter.

Query parameters

Parameter	Type	Description
currency	string	3-letter ISO currency code for price conversion (e.g. EUR, GBP)
fields	string	Comma-separated fields to return

Request

curl https://api.hydrajs.dev/v1/cart/cart_abc123 \
  -H "Authorization: Bearer pk_live_YOUR_KEY"

Response 200

{
	"data": {
		"id": "cart_abc123",
		"currency": "USD",
		"items": [
			{
				"id": "ci_aaa111",
				"variant_id": "var_def456",
				"product_id": "prod_abc123",
				"title": "Classic T-Shirt",
				"variant_title": "Medium / Black",
				"image": "https://cdn.hydrajs.dev/stores/store_xxx/img_ghi789.webp",
				"quantity": 2,
				"unit_price": 2999,
				"price_key": null,
				"total": 5998,
				"created_at": "2026-08-17T10:05:00Z",
				"updated_at": "2026-08-17T10:05:00Z"
			},
			{
				"id": "ci_bbb222",
				"variant_id": "var_ghi012",
				"product_id": "prod_xyz789",
				"title": "Slim Jeans",
				"variant_title": "32W / Indigo",
				"image": "https://cdn.hydrajs.dev/stores/store_xxx/img_jkl012.webp",
				"quantity": 1,
				"unit_price": 5999,
				"price_key": null,
				"total": 5999,
				"created_at": "2026-08-17T10:06:00Z",
				"updated_at": "2026-08-17T10:06:00Z"
			}
		],
		"item_count": 3,
		"subtotal": 11997,
		"created_at": "2026-08-17T10:00:00Z",
		"updated_at": "2026-08-17T10:06:00Z"
	}
}

---

Add item to cart

POST /v1/cart/{id}/items

Adds a variant to the cart. If the same variant (and price key) is already in the cart, the quantity is incremented instead of creating a duplicate line item.

Request body

Field	Type	Required	Description
variant_id	string	Yes	Variant ID to add
quantity	integer	No	Quantity to add (1–999, default: 1)
price_key	string	No	Price tier key slug (requires price_keys extension)

Request

curl -X POST https://api.hydrajs.dev/v1/cart/cart_abc123/items \
  -H "Authorization: Bearer pk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "variant_id": "var_def456",
    "quantity": 2
  }'

Response 200

Returns the full cart object (same shape as Get a cart) with the updated items and totals.

---

Update item quantity

PATCH /v1/cart/{id}/items/{item_id}

Sets the quantity for an existing cart item. Setting quantity to 0 removes the item from the cart.

Request body

Field	Type	Required	Description
quantity	integer	Yes	New quantity (0–999). 0 removes the item

Request

curl -X PATCH https://api.hydrajs.dev/v1/cart/cart_abc123/items/ci_aaa111 \
  -H "Authorization: Bearer pk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"quantity": 3}'

Response 200

Returns the full cart object with updated totals.

---

Remove item from cart

DELETE /v1/cart/{id}/items/{item_id}

Removes a specific item from the cart.

Request

curl -X DELETE https://api.hydrajs.dev/v1/cart/cart_abc123/items/ci_aaa111 \
  -H "Authorization: Bearer pk_live_YOUR_KEY"

Response 200

Returns the full cart object with the item removed and totals recalculated.

---

Clear cart

DELETE /v1/cart/{id}

Removes all items from the cart but keeps the cart itself alive.

Request

curl -X DELETE https://api.hydrajs.dev/v1/cart/cart_abc123 \
  -H "Authorization: Bearer pk_live_YOUR_KEY"

Response 200

{
	"data": {
		"id": "cart_abc123",
		"currency": "USD",
		"items": [],
		"item_count": 0,
		"subtotal": 0,
		"created_at": "2026-08-17T10:00:00Z",
		"updated_at": "2026-08-17T10:30:00Z"
	}
}

---

The cart object

Field	Type	Description
id	string	Unique ID (prefix: cart_)
currency	string	3-letter ISO currency code (inherited from the project)
items	object[]	Array of cart items (see below)
item_count	integer	Total quantity across all items
subtotal	integer	Sum of all item totals, in cents
display_currency	string	Present only when ?currency= conversion is applied
created_at	string	ISO 8601 timestamp
updated_at	string	ISO 8601 timestamp

Cart item fields

Field	Type	Description
id	string	Unique ID (prefix: ci_)
variant_id	string	Variant ID
product_id	string	Product ID
title	string	Product title (snapshotted at add time)
variant_title	string	Variant title (snapshotted at add time)
image	string | null	First product image URL (snapshotted at add time)
quantity	integer	Item quantity
unit_price	integer	Price per unit in cents (snapshotted at add time)
price_key	string | null	Price tier slug (if using price_keys extension)
total	integer	unit_price * quantity
created_at	string	ISO 8601 timestamp
updated_at	string	ISO 8601 timestamp