BrainerceAdd to cart
Adds a product (or variant) to the cart, or raises the quantity of the same line. Stock is checked, and reserved when the channel reserves on add to cart. Optional selections, nestedByModifierId and notes configure modifier groups and line notes; customizations carries customer-input fields.
For /api/vc/{connectionId}/* routes the connectionId (vc_*) is in the URL path — not a header. Live-mode requests must also send a matching Origin header.
In: header
Path Parameters
Sales channel ID (vc_*), the canonical salesChannelId. connectionId is the deprecated name of the same value and is still the literal path segment.
Cart id, returned by cart (create cart).
Query Parameters
Language code, for example he. Used only when no Accept-Language header is sent. A language the store does not support, or the store's default language, returns the default text.
Proof that the caller holds this cart. For a guest cart send the cart sessionToken (returned when the cart was created). Required on every cart write when the store runs cart ownership in enforce mode; a missing or wrong token answers 403 CART_ACCESS_DENIED (never 401). A customer cart is proven by the customer Bearer token instead. Send either the cartToken query parameter or the X-Cart-Session header.
Header Parameters
Origin of the storefront page making the call, for example https://shop.example.com. Required: a request with no Origin header is refused with 403. On a LIVE channel its host must equal the channel's registered domain (or one of its subdomains) or match an allowed origin. A TEST channel with no domain accepts any origin; once a domain is set it is matched as on LIVE.
Preferred language, for example he. Its first tag is used when it is one of the store's supported languages other than the default; translated fields are then returned in that language. Falls back to the locale query parameter.
Version of the calling SDK (the Brainerce SDK sends it automatically). Informational: it is recorded on the channel and never changes the response.
Proof that the caller holds this cart. For a guest cart send the cart sessionToken (returned when the cart was created). Required on every cart write when the store runs cart ownership in enforce mode; a missing or wrong token answers 403 CART_ACCESS_DENIED (never 401). A customer cart is proven by the customer Bearer token instead. Send either the cartToken query parameter or the X-Cart-Session header.
Product to add.
Variant id for the product, if it has variants.
Number of units to add (1..1000).
1 <= value <= 1000Shopper-facing note attached to this line item ("Please gift-wrap"). Max 2000 chars.
length <= 2000Free-form JSON metadata you want to carry through to the order line, for any purpose of your own. Also where customer-input values go, keyed by metafield definition key, when the product has customization fields. Not displayed in the storefront UI. Max 4 KB, depth ≤ 3, no prototype keys.
GA4 gtag.js client_id (from gtag('get', measurementId, 'client_id', cb)), forwarded so a later server-side purchase event can stitch to this browser session. Written onto the cart if not already set. Omit if unavailable, and never send a synthesized id.
length <= 100GA4 gtag.js session_id (from gtag('get', measurementId, 'session_id', cb)), forwarded alongside analyticsClientId for the same stitch.
length <= 100Modifier selections grouped by modifierGroupId, in click-order. Omit for products without modifier groups.
Nested combo specs (for modifiers with referencedProductId). Keyed by parent modifier id; validator rejects depth > 3.
curl -X POST "https://api.brainerce.com/api/vc/string/cart/string/items?locale=string&cartToken=string" \ -H "origin: string" \ -H "accept-language: string" \ -H "X-SDK-Version: string" \ -H "x-cart-session: string" \ -H "Content-Type: application/json" \ -d '{ "productId": "prod_abc123", "quantity": 1 }'{
"id": "clcrt_abc123",
"sessionToken": "string",
"customerId": "clcustomer_abc123",
"status": "ACTIVE",
"currency": "USD",
"notes": "string",
"analyticsClientId": "clanalyticsclient_abc123",
"analyticsSessionId": "clanalyticssession_abc123",
"subtotal": "39.80",
"discountAmount": "5.00",
"ruleDiscountAmount": "0",
"promoDiscountTotal": "0",
"couponCode": "WELCOME10",
"appliedDiscounts": [
{
"ruleId": "cldr_abc123",
"ruleName": "string",
"type": "PRODUCT_DISCOUNT",
"discountAmount": "5.00",
"description": "string"
}
],
"nudges": [
{
"ruleId": "cldr_abc123",
"text": "string",
"type": "AMOUNT_NEEDED",
"amountNeeded": "12.00",
"quantityNeeded": 1
}
],
"items": [
{
"id": "clx1234567890",
"productId": "clprd_abc123",
"variantId": "clvariant_abc123",
"quantity": 2,
"unitPrice": "19.90",
"currentUnitPrice": "21.90",
"priceChanged": true,
"priceDelta": "2.00",
"priceDirection": "increased",
"isAvailable": true,
"unavailableReason": null,
"discountAmount": "0",
"promoDiscountAmount": "0",
"promoSource": "BUNDLE",
"promoSourceId": "clpromosource_abc123",
"notes": "string",
"metadata": {},
"customizations": {},
"product": {
"id": "clprd_abc123",
"name": "string",
"sku": "MUG-BLU",
"images": [
{
"url": "https://cdn.brainerce.com/products/abc123.jpg",
"alt": "Blue mug"
}
]
},
"variant": {
"id": "clvar_abc123",
"name": "string",
"sku": "MUG-BLU-L",
"image": {
"url": "https://cdn.brainerce.com/products/abc123.jpg",
"alt": "Blue mug"
}
},
"modifiers": [
{
"modifierId": "clmod_abc123",
"modifierGroupId": "clmgr_abc123",
"name": "string",
"priceDelta": "1.50",
"freeApplied": false,
"effectivePrice": "1.50",
"positionInGroup": 0
}
],
"modifiersTotal": "1.50",
"parentCartItemId": "clparentcartitem_abc123",
"createdAt": "2026-01-15T10:30:00.000Z",
"updatedAt": "2026-01-15T10:30:00.000Z"
}
],
"itemCount": 3,
"hasPriceChanges": false,
"hasUnavailableItems": false,
"unavailableItemIds": [],
"expiresAt": "2026-01-15T10:30:00.000Z",
"createdAt": "2026-01-15T10:30:00.000Z",
"updatedAt": "2026-01-15T10:30:00.000Z",
"reservation": {
"hasReservation": true,
"expiresAt": "2026-01-15T10:30:00.000Z",
"remainingSeconds": 540,
"strategy": "ON_CART",
"countdownMessage": "string"
},
"recommendations": {
"recommendations": [
{
"id": "clprd_abc123",
"name": "string",
"slug": "blue-mug",
"basePrice": "24.00",
"salePrice": "19.99",
"images": [
{
"url": "https://cdn.brainerce.com/products/abc123.jpg",
"alt": "Blue mug"
}
],
"type": "SIMPLE",
"inventory": {
"total": 42,
"available": 39,
"trackingMode": "TRACKED",
"inStock": true,
"canPurchase": true
},
"targetVariantId": null,
"requiresVariantSelection": false,
"pinnedVariant": {
"id": "clvar_abc123",
"name": "string",
"attributes": {}
},
"variants": [
{
"id": "clvar_abc123",
"name": "string",
"attributes": {},
"image": {
"url": "https://cdn.brainerce.com/products/abc123.jpg",
"alt": "Blue mug"
},
"price": "24.00",
"salePrice": null
}
],
"relationType": "CROSS_SELL"
}
]
},
"upgrades": {
"upgrades": {}
},
"bundles": {
"bundles": [
{
"id": "clx1234567890",
"name": "string",
"description": "string",
"triggerProductId": "cltriggerproduct_abc123",
"productIds": [
"string"
],
"offeredProducts": [
{
"id": "clprd_abc123",
"name": "string",
"slug": "blue-mug",
"basePrice": "30.00",
"salePrice": "19.99",
"images": [
{
"url": "https://cdn.brainerce.com/products/abc123.jpg",
"alt": "Blue mug"
}
],
"type": "SIMPLE",
"variantId": "clvariant_abc123",
"requiresVariantSelection": false,
"pinnedVariant": {
"id": "clvar_abc123",
"name": "string",
"attributes": {}
},
"variants": [
{
"id": "clvar_abc123",
"name": "string",
"attributes": {},
"image": {
"url": "https://cdn.brainerce.com/products/abc123.jpg",
"alt": "Blue mug"
},
"price": "24.00",
"salePrice": null
}
],
"originalPrice": "30.00",
"discountedPrice": "24.00"
}
],
"discountType": "PERCENTAGE",
"discountValue": "20",
"totalOriginalPrice": "30.00",
"totalDiscountedPrice": "24.00"
}
]
}
}{
"statusCode": 400,
"code": "VALIDATION_FAILED",
"message": "name should not be empty, price must be a positive number",
"timestamp": "2026-08-23T10:15:00.000Z",
"path": "/api/vc/{connectionId}/cart/{cartId}/items"
}{
"statusCode": 403,
"code": "INSUFFICIENT_SCOPE",
"message": "API key does not have the required scope: products:write",
"timestamp": "2026-08-23T10:15:00.000Z",
"path": "/api/vc/{connectionId}/cart/{cartId}/items"
}{
"statusCode": 404,
"code": "RESOURCE_NOT_FOUND",
"message": "Resource not found",
"timestamp": "2026-08-23T10:15:00.000Z",
"path": "/api/vc/{connectionId}/cart/{cartId}/items"
}{
"statusCode": 409,
"code": "CONFLICT",
"message": "The request conflicts with the current state of the resource",
"timestamp": "2026-08-23T10:15:00.000Z",
"path": "/api/vc/{connectionId}/cart/{cartId}/items"
}{
"statusCode": 429,
"code": "RATE_LIMITED",
"message": "Too many requests",
"details": {
"retryAfterSeconds": 12
},
"timestamp": "2026-08-23T10:15:00.000Z",
"path": "/api/vc/{connectionId}/cart/{cartId}/items"
}