API overview
Add a configured product to the cart
Choose an operation to see its request, response shape, access rules and implementation source.
WritePublic cart context
POST/api/v1/cart
Add a configured product to the cart
No auth:sanctum or bearer ability is required by this route.
Request
| Field | In | Rule |
|---|---|---|
X-Cart-Token | Header | Guest cart credential returned by the cart API. Preserve it; a missing or malformed token starts a new cart context. |
product_id | JSON body | Required integer; product must be purchasable in the current currency and capability context. |
quantity | JSON body | Nullable integer, 1 to 99; default 1. |
selections | JSON body | Nullable array/map of product option keys and selected values; validated by the cart service. |
curl --request POST "https://shop.example.test/api/v1/cart" \
--header 'Accept: application/json' \
--header "X-Cart-Token: $CART_TOKEN" \
--header 'Content-Type: application/json' \
--data '{"product_id":42,"quantity":1,"selections":{}}'Response200
Success: 200
Response shape (notation, not a captured response)
{ data: { token: string, item_count: integer, requires_shipping: boolean, subtotal_amount: integer|null, currency: string|null, lines: CartLine[] } }Response header: X-Cart-Token matches data.token.
Common errors
| HTTP status | Meaning |
|---|---|
422 | validation_error: invalid input or unmet domain requirements. Payment initiation can also return payment_failed. |
429 | rate_limited: back off before retrying, especially writes. |