Brainerce
Help CenterPricingResourcesDashboard
API ReferenceEndpointsCartAdd item to cart

Add item to cart

Supports Idempotency-Key header for safe retries.

POST
/v1/cart/{cartId}/items

Authorization

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

Path Parameters

cartIdstring

Cart ID

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 Conflict with code: "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 GET returns 400 with code: "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.

See /docs/api/idempotency.

Lengthlength <= 255

Request Body

productIdstring

Product to add.

variantId?string

Variant id for the product, if it has variants.

quantityinteger

Number of units to add (1..1000).

Range1 <= value <= 1000
notes?string

Shopper-facing note attached to this line item ("Please gift-wrap"). Max 2000 chars.

Lengthlength <= 2000
metadata?object

Free-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.

analyticsClientId?string

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.

Lengthlength <= 100
analyticsSessionId?string

GA4 gtag.js session_id (from gtag('get', measurementId, 'session_id', cb)), forwarded alongside analyticsClientId for the same stitch.

Lengthlength <= 100
recommendationToken?string

The recToken of the recommendation card this product was added from, exactly as the API returned it. Only the units added in this call are credited to the recommendation. A token that is invalid, expired, issued for another store or channel, or issued for a different product is ignored (the add still succeeds). Read by the storefront routes only; ignored elsewhere.

Lengthlength <= 1024
selections?array<ModifierSelectionDto>

Modifier selections grouped by modifierGroupId, in click-order. Omit for products without modifier groups.

nestedByModifierId?object

Nested combo specs (for modifiers with referencedProductId). Keyed by parent modifier id; validator rejects depth > 3.

curl -X POST "https://api.brainerce.com/api/v1/cart/string/items" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{    "productId": "prod_abc123",    "quantity": 1  }'
{
  "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/{cartId}/items"
}

{
  "statusCode": 401,
  "code": "UNAUTHORIZED",
  "message": "Invalid or expired credential",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/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/v1/cart/{cartId}/items"
}

{
  "statusCode": 404,
  "code": "RESOURCE_NOT_FOUND",
  "message": "Resource not found",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/cart/{cartId}/items"
}

{
  "statusCode": 429,
  "code": "RATE_LIMITED",
  "message": "Too many requests",
  "details": {
    "retryAfterSeconds": 12
  },
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/store"
}

Get cart by customer ID

Returns the most recently updated active cart of the customer.

Update cart item (Public API)

Update cart item (Public API). PATCH /v1/cart/{cartId}/items/{itemId} in the Brainerce API.