## Aggregated product stock

`GET /v1/warehouses/stock/totals`

Sums each product's stock across all warehouses in your Bitrix24 account. For each product, it returns the total quantity, the total reserve, and the list of warehouses where the product is present. Read-only.

## Query parameters

| Parameter | Type | Default | Description |
|----------|-----|-----------|---------|
| `productId` | number | — | Aggregate stock for a single product only |
| `limit` | number | — | How many products to return in the response |
| `offset` | number | `0` | Offset within the product list |

## Examples

### curl — personal key

```bash
curl "https://vibecode.bitrix24.com/v1/warehouses/stock/totals?productId=200" \
  -H "X-Api-Key: YOUR_API_KEY"
```

### curl — OAuth application

```bash
curl "https://vibecode.bitrix24.com/v1/warehouses/stock/totals?productId=200" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"
```

### JavaScript — personal key

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/warehouses/stock/totals', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data, meta } = await res.json()
```

### JavaScript — OAuth application

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/warehouses/stock/totals', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { success, data, meta } = await res.json()
```

## Response fields

| Field | Type | Description |
|------|-----|---------|
| `success` | boolean | Always `true` on success |
| `data` | array | Per-product summary |
| `data[].productId` | number | Product identifier — see [Catalog products](/docs/entities/catalog-products) |
| `data[].amount` | number | Total product quantity across all warehouses |
| `data[].quantityReserved` | number | Total product reserve across all warehouses |
| `data[].storeIds` | array | Identifiers of warehouses where the product is present |
| `meta.total` | number | Total number of products in the summary, before `limit` and `offset` are applied |
| `meta.rawTotal` | number | Number of source stock rows in the Bitrix24 selection. When `truncated` is `true`, it exceeds the number of rows that made it into the summary |
| `meta.truncated` | boolean | `true` if there are more than 5000 source stock rows and some did not make it into the summary |

## Response example

```json
{
  "success": true,
  "data": [
    {
      "productId": 200,
      "amount": 25,
      "quantityReserved": 30,
      "storeIds": [1, 2, 5]
    }
  ],
  "meta": {
    "total": 1,
    "truncated": false,
    "rawTotal": 3
  }
}
```

## Error response example

400 — invalid `productId`:

```json
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "productId must be a positive integer in canonical form — digits only, no leading zero, sign, fraction or exponent"
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|---------|
| 400 | `INVALID_PARAMS` | `productId` or `limit` is not a canonical positive integer (`100.9`, `100abc`, `1e2`, `0100` are rejected), or `offset` is negative |
| 400 | `UNSUPPORTED_FILTER` | a `filter[]` parameter was passed — this endpoint does not support it and does not forward it to Bitrix24 |
| 401 | `TOKEN_MISSING` | The API key has no configured tokens |
| 403 | `SCOPE_DENIED` | The API key does not have the `catalog` scope |
| 502 | `BITRIX_UNAVAILABLE` | Bitrix24 is unavailable |

The full list of common API errors — [Errors](/docs/errors).

## Known specifics

**Summing per product.** One product's quantity and reserve are summed across all warehouses where it is present. The list of such warehouses is in `storeIds`. If quantity is not set in a particular warehouse, it is counted as zero when summing.

**Summary limit.** The summary is computed over the first 5000 stock rows. If there are more rows, `meta.truncated` is `true` and the summary is incomplete. In that case, narrow the selection with the `productId` parameter.

## See also

- [Warehouse stock](/docs/entities/warehouses/stock)
- [List warehouses](/docs/entities/warehouses/list)
- [Catalog products](/docs/entities/catalog-products)
- [API reference](/docs/api-reference)