Inventory

Inventory tracks stock per product/variant: total, reserved (held by active checkouts), and available (total - reserved). Use these endpoints to adjust stock manually, run bulk lookups, check availability, and reconcile drift between Brainerce and external platforms.

Get inventory

Authorization

X-Sales-Channel-Origin<token>

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

connectionIdstring

Query Parameters

productIdsstring

Header Parameters

originstring

curl -X GET "https://api.brainerce.com/api/vc/string/inventory?productIds=string" \
  -H "origin: string"

curl -X GET "https://api.brainerce.com/api/vc/string/inventory?productIds=string" \  -H "origin: string"

{
  "inventory": [
    {
      "productId": "clprd_abc123",
      "sku": "MUG-BLU",
      "name": "Blue mug",
      "type": "SIMPLE",
      "inventory": {
        "total": 42,
        "reserved": 3,
        "available": 39,
        "trackingMode": "TRACKED",
        "inStock": true,
        "canPurchase": true
      },
      "variants": [
        {
          "variantId": "clvar_abc123",
          "sku": "MUG-BLU-L",
          "name": "Blue / Large",
          "inventory": {
            "total": 42,
            "reserved": 3,
            "available": 39,
            "trackingMode": "TRACKED",
            "inStock": true,
            "canPurchase": true
          }
        }
      ]
    }
  ]
}

Check stock availability

Authorization

X-Sales-Channel-Origin<token>

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

connectionIdstring

Header Parameters

originstring

Request Body

itemsarray<VcCartItemDto>

Line items. At most 50 per request.

Itemsitems <= 50

curl -X POST "https://api.brainerce.com/api/vc/string/inventory/check-availability" \
  -H "origin: string" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "productId": "clx1234567890",
        "quantity": 2
      }
    ]
  }'

curl -X POST "https://api.brainerce.com/api/vc/string/inventory/check-availability" \  -H "origin: string" \  -H "Content-Type: application/json" \  -d '{    "items": [      {        "productId": "clx1234567890",        "quantity": 2      }    ]  }'

{
  "allAvailable": true,
  "results": [
    {
      "productId": "clprd_abc123",
      "variantId": "clvar_abc123",
      "isAvailable": true,
      "available": 12,
      "requested": 2,
      "shortfall": 0,
      "trackingMode": "TRACKED"
    }
  ]
}

Get availability

Returns per-product stock figures accounting for active reservations. Cap of 50 productIds per request.

Authorization

X-Sales-Channel-Origin<token>

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

connectionIdstring

Sales-channel connection ID (vc_*)

Header Parameters

origin?string

Request Body

productIdsarray<string>

Products to report availability for.

curl -X POST "https://api.brainerce.com/api/vc/string/availability" \
  -H "origin: string" \
  -H "Content-Type: application/json" \
  -d '{
    "productIds": [
      "string"
    ]
  }'

curl -X POST "https://api.brainerce.com/api/vc/string/availability" \  -H "origin: string" \  -H "Content-Type: application/json" \  -d '{    "productIds": [      "string"    ]  }'

[
  {
    "productId": "string",
    "variantId": "string",
    "trackingMode": "TRACKED",
    "total": 0,
    "reserved": 0,
    "available": 0,
    "canPurchase": true,
    "lowStock": true
  }
]

Extend reservation

Extends the expiry of an active reservation for a cart or checkout. Returns 400 if the sales-channel reservation strategy is ON_PAYMENT.

Authorization

X-Sales-Channel-Origin<token>

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

connectionIdstring

Sales-channel connection ID (vc_*)

Header Parameters

origin?string

Request Body

cartId?string

Cart whose stock reservation this affects.

checkoutId?string

Checkout whose stock reservation this affects.

curl -X POST "https://api.brainerce.com/api/vc/string/reservation/extend" \
  -H "origin: string" \
  -H "Content-Type: application/json" \
  -d '{}'

curl -X POST "https://api.brainerce.com/api/vc/string/reservation/extend" \  -H "origin: string" \  -H "Content-Type: application/json" \  -d '{}'

{
  "success": true,
  "reservation": {
    "hasReservation": true,
    "expiresAt": "2019-08-24T14:15:22Z",
    "remainingSeconds": 0,
    "strategy": "string",
    "countdownMessage": "string"
  }
}

Release reservation

Releases an active reservation for a cart or checkout (e.g. shopper abandoned the flow). No-op if no active reservations are found. Returns 400 if the strategy is ON_PAYMENT.

Authorization

X-Sales-Channel-Origin<token>

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

connectionIdstring

Sales-channel connection ID (vc_*)

Header Parameters

origin?string

Request Body

cartId?string

Cart whose stock reservation this affects.

checkoutId?string

Checkout whose stock reservation this affects.

curl -X POST "https://api.brainerce.com/api/vc/string/reservation/release" \
  -H "origin: string" \
  -H "Content-Type: application/json" \
  -d '{}'

curl -X POST "https://api.brainerce.com/api/vc/string/reservation/release" \  -H "origin: string" \  -H "Content-Type: application/json" \  -d '{}'

{
  "success": true
}

Request a back-in-stock alert

Records a "notify me when this is back" request for an out-of-stock product or variant. Nothing is mailed at request time — exactly one email goes out later, once the item is genuinely available again on this sales channel and has stayed that way. Pass variantId for a variable product: an alert on the blue medium fires only for the blue medium, never when some other size returns.

Unlike POST /marketing/subscribe this needs no confirmation round trip, because it grants no marketing consent and creates no customer account. It is not a newsletter signup and must not be presented as one.

The response is identical for a new request, a duplicate, an unknown product and an item that is already in stock, so it cannot be used to read this store's stock levels or customer list — do not branch on it to tell the shopper whether the item is in stock.

No authentication. Include the honeypot field as a hidden, empty input. Rate limited to 5 requests per minute rather than the inquiry route's 3, because a shopper legitimately asks about several sizes in a row and no mail leaves at request time anyway.

Authorization

X-Sales-Channel-Origin<token>

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

connectionIdstring

Sales-channel connection ID (vc_*)

Header Parameters

origin?string

Request Body

emailstring

Address to notify. Lowercased and trimmed server-side. Receives exactly one email, when the item is back.

Lengthlength <= 254

productIdstring

Product the shopper is waiting for.

variantId?string

Specific variant, when the product has them. Omit for a simple product. An alert on the blue medium fires only when the blue medium is back, never when some other size returns.

locale?string

Storefront locale at submission time (e.g. "he"). Sets the language of the alert email. Falls back to the store language.

Lengthlength <= 10

honeypot?string

Anti-bot honeypot. Render it hidden and leave it empty; a filled value rejects the request. Bots complete every text input, humans never see this one.

curl -X POST "https://api.brainerce.com/api/vc/string/stock-alerts" \
  -H "origin: string" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "productId": "clx1a2b3c4d5e6f7g8h9"
  }'

curl -X POST "https://api.brainerce.com/api/vc/string/stock-alerts" \  -H "origin: string" \  -H "Content-Type: application/json" \  -d '{    "email": "[email protected]",    "productId": "clx1a2b3c4d5e6f7g8h9"  }'

{
  "ok": true
}

Get inventory for a product

Authorization

AuthorizationBearer <token>

Admin API key (server-to-server). Issue via the dashboard at Settings → Authentication → API Keys. Plain-text key is shown once — store in a secret manager. Format: Authorization: Bearer brainerce_xxxxxxxxx.

In: header

Path Parameters

idstring

Product ID

curl -X GET "https://api.brainerce.com/api/v1/products/string/inventory"

curl -X GET "https://api.brainerce.com/api/v1/products/string/inventory"

{
  "id": "string",
  "productId": "string",
  "trackingMode": "TRACKED",
  "backorderMode": "string",
  "backorderLimit": 0,
  "total": 0,
  "reserved": 0,
  "available": 0,
  "lowStockThreshold": 0,
  "lastInventorySyncAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

{
  "statusCode": 401,
  "code": "UNAUTHORIZED",
  "message": "Invalid or expired credential",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/products/{id}/inventory"
}

{
  "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/products/{id}/inventory"
}

Update inventory for a product

Supports Idempotency-Key header for safe retries. ⛔ Rejects a KIT with 400: a kit holds no stock of its own — its availability is MIN(floor(component.available / quantity)), recomputed from its components on every read. Set the stock on the component products instead.

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

quantitynumber

New absolute stock level

variantId?string

Variant ID (optional)

curl -X PUT "https://api.brainerce.com/api/v1/products/string/inventory" \
  -H "Idempotency-Key: string" \
  -H "Content-Type: application/json" \
  -d '{
    "quantity": 0
  }'

curl -X PUT "https://api.brainerce.com/api/v1/products/string/inventory" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{    "quantity": 0  }'

{
  "id": "string",
  "productId": "string",
  "trackingMode": "TRACKED",
  "backorderMode": "string",
  "backorderLimit": 0,
  "total": 0,
  "reserved": 0,
  "available": 0,
  "lowStockThreshold": 0,
  "lastInventorySyncAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

{
  "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/products/{id}/inventory"
}

{
  "statusCode": 401,
  "code": "UNAUTHORIZED",
  "message": "Invalid or expired credential",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/products/{id}/inventory"
}

{
  "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/products/{id}/inventory"
}

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

Example default

Example default

Example default

Example default

Example default

Example default

On this page