BrainerceCreate cart
Creates an empty cart. With a valid customer Authorization token the cart belongs to that customer; without one (or with an invalid one) a guest cart is created and its sessionToken is the proof needed for later writes.
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.
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.
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.
Optional customer token as Bearer <token>. Present and valid: the cart is linked to the customer. Absent or invalid: a guest cart is created, an invalid token is not an error.
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.
Optional. Only analyticsClientId and analyticsSessionId are read on this route; the session token is always minted server-side and customerId comes from the Bearer token, never from the body.
Existing session token to attach this cart to. Omit on the first call, and the server will generate a fresh token and return it on the response. Only supply on retry / explicit re-attach flows.
Customer id to associate the cart with. Only honoured for admin / server-to-server callers. Sales-channel callers must instead send a Authorization: Bearer <customer-token> header.
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. 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 <= 100curl -X POST "https://api.brainerce.com/api/vc/string/cart?locale=string" \ -H "origin: string" \ -H "authorization: string" \ -H "accept-language: string" \ -H "X-SDK-Version: string" \ -H "Content-Type: application/json" \ -d '{}'{
"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"
}{
"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"
}{
"statusCode": 404,
"code": "RESOURCE_NOT_FOUND",
"message": "Resource not found",
"timestamp": "2026-08-23T10:15:00.000Z",
"path": "/api/vc/{connectionId}/cart"
}{
"statusCode": 429,
"code": "RATE_LIMITED",
"message": "Too many requests",
"details": {
"retryAfterSeconds": 12
},
"timestamp": "2026-08-23T10:15:00.000Z",
"path": "/api/vc/{connectionId}/cart"
}