BrainerceMerge guest cart into customer cart
Supports Idempotency-Key header for safe retries.
AuthorizationBearer <token>
Admin API key (server-to-server). Issue via the dashboard at Settings → API keys. Plain-text key is shown once — store in a secret manager. Format: Authorization: Bearer brainerce_xxxxxxxxx.
In: header
Header Parameters
Idempotency-Key?string
Client-supplied key (a UUID v4 is the recommended form, max 255 characters) that makes this mutation safe to retry.
- Replay window: 24 hours. The first response for a key is cached; a retry inside the window with the same request body returns the original status and body without re-running the handler.
- Reusing a key with a different body returns
409 Conflictwithcode: "IDEMPOTENCY_KEY_REUSED". The request fingerprint (method + path + body hash) is compared against the stored one; a mismatch is refused rather than served the old response. - Keys are scoped to the calling credential and store — two API keys may safely use the same key value.
- Error responses are cached too, so a retry of a request that failed validation returns the same 400 immediately.
- Sending this header on a
GETreturns400withcode: "IDEMPOTENCY_KEY_NOT_SUPPORTED"— GETs are already idempotent. - Support is per-route and this parameter is the authoritative signal: a key sent to a route that does not declare it is accepted and silently ignored.
Length
length <= 255sessionTokenstring
Opaque session token identifying the guest cart to merge. Returned by POST /cart when no customer token is supplied. Treat it as a secret: anyone holding it can read or modify the guest cart.
customerIdstring
ID of the customer whose cart receives the guest items. Must belong to the store the API key is bound to.
curl -X POST "https://api.brainerce.com/api/v1/cart/merge" \ -H "Idempotency-Key: string" \ -H "Content-Type: application/json" \ -d '{ "sessionToken": "sess_01HX7Y6F8M9R0K2N3P4Q5R6S7T", "customerId": "clcus_abc123" }'{
"id": "clx1a2b3c4d5e6f7g8h9",
"sessionToken": "cs_7d9f2a1b3c4e5f60",
"customerId": "clx1a2b3c4d5e6f7g8h9",
"status": "ACTIVE",
"currency": "USD",
"notes": "Leave at the door",
"analyticsClientId": "clx1a2b3c4d5e6f7g8h9",
"analyticsSessionId": "clx1a2b3c4d5e6f7g8h9",
"subtotal": "59.80",
"discountAmount": "5.00",
"ruleDiscountAmount": "5.00",
"promoDiscountTotal": "0.00",
"couponCode": "WELCOME10",
"appliedDiscounts": [
{
"ruleId": "clx1a2b3c4d5e6f7g8h9",
"ruleName": "Summer sale",
"type": "ORDER_DISCOUNT",
"discountAmount": "10.00",
"description": "10% off orders over 200"
}
],
"nudges": [
{
"ruleId": "clx1a2b3c4d5e6f7g8h9",
"text": "Add 20.00 more for free shipping",
"type": "AMOUNT_NEEDED",
"amountNeeded": "20.00",
"quantityNeeded": 1
}
],
"items": [
{
"id": "clx1a2b3c4d5e6f7g8h9",
"productId": "clx1a2b3c4d5e6f7g8h9",
"variantId": "clx1a2b3c4d5e6f7g8h9",
"quantity": 2,
"unitPrice": "29.90",
"currentUnitPrice": "31.90",
"priceChanged": true,
"priceDelta": "2.00",
"priceDirection": "increased",
"isAvailable": true,
"unavailableReason": "PRODUCT_DRAFT",
"discountAmount": "0.00",
"promoDiscountAmount": "0.00",
"promoSource": "BUNDLE",
"promoSourceId": "clx1a2b3c4d5e6f7g8h9",
"notes": "Gift wrap please",
"metadata": {},
"customizations": {},
"product": {
"id": "clx1a2b3c4d5e6f7g8h9",
"name": "Classic T-Shirt",
"sku": "TSHIRT-BLK-M",
"images": [
{}
]
},
"variant": {
"id": "clx1a2b3c4d5e6f7g8h9",
"name": "Black / M",
"sku": "TSHIRT-BLK-M",
"image": {
"url": "string",
"alt": "string"
}
},
"modifiers": [
{
"modifierId": "clx1a2b3c4d5e6f7g8h9",
"modifierGroupId": "clx1a2b3c4d5e6f7g8h9",
"name": "Extra cheese",
"priceDelta": "5.00",
"freeApplied": true,
"effectivePrice": "5.00",
"positionInGroup": 0
}
],
"modifiersTotal": "5.00",
"parentCartItemId": "clx1a2b3c4d5e6f7g8h9",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"itemCount": 2,
"hasPriceChanges": true,
"hasUnavailableItems": true,
"unavailableItemIds": [
"string"
],
"expiresAt": "2019-08-24T14:15:22Z",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"reservation": {
"hasReservation": true,
"expiresAt": "2019-08-24T14:15:22Z",
"remainingSeconds": 540,
"strategy": "ON_PAYMENT",
"countdownMessage": "Your items are reserved for 9 minutes"
},
"recommendations": {
"recommendations": [
{
"id": "string",
"name": "string",
"slug": "string",
"basePrice": "string",
"salePrice": "string",
"images": [
{
"url": "string",
"alt": "string"
}
],
"type": "SIMPLE",
"inventory": {
"total": 0,
"available": 0,
"trackingMode": "TRACKED",
"inStock": true,
"canPurchase": true
},
"relationType": "string",
"targetVariantId": "string",
"requiresVariantSelection": true,
"pinnedVariant": {
"id": "string",
"name": "string",
"attributes": {}
},
"variants": [
{
"id": "string",
"name": "string",
"attributes": {},
"image": {
"url": "string",
"alt": "string"
},
"price": "string",
"salePrice": "string"
}
]
}
]
},
"upgrades": {
"upgrades": {}
},
"bundles": {
"bundles": [
{
"id": "string",
"name": "string",
"description": "string",
"triggerProductId": "string",
"productIds": [
"string"
],
"offeredProducts": [
{
"id": "string",
"name": "string",
"slug": "string",
"basePrice": "string",
"salePrice": "string",
"images": [
{
"url": "string",
"alt": "string"
}
],
"type": "SIMPLE",
"variantId": "string",
"requiresVariantSelection": true,
"pinnedVariant": {
"id": "string",
"name": "string",
"attributes": {}
},
"variants": [
{
"id": "string",
"name": "string",
"attributes": {},
"image": {
"url": "string",
"alt": "string"
},
"price": "string",
"salePrice": "string"
}
],
"originalPrice": "string",
"discountedPrice": "string"
}
],
"discountType": "PERCENTAGE",
"discountValue": "string",
"totalOriginalPrice": "string",
"totalDiscountedPrice": "string"
}
]
}
}{
"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/v1/cart/merge"
}{
"statusCode": 401,
"code": "UNAUTHORIZED",
"message": "Invalid or expired credential",
"timestamp": "2026-08-23T10:15:00.000Z",
"path": "/api/v1/cart/merge"
}{
"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/v1/cart/merge"
}{
"statusCode": 404,
"code": "RESOURCE_NOT_FOUND",
"message": "Resource not found",
"timestamp": "2026-08-23T10:15:00.000Z",
"path": "/api/v1/cart/merge"
}{
"statusCode": 429,
"code": "RATE_LIMITED",
"message": "Too many requests",
"details": {
"retryAfterSeconds": 12
},
"timestamp": "2026-08-23T10:15:00.000Z",
"path": "/api/v1/store"
}