[{"data":1,"prerenderedAt":16},["ShallowReactive",2],{"docs-entities\u002Fshipment-items":3,"docs-tabs-entities\u002Fshipment-items":6},{"content":4,"lastmod":5},"# Shipment items\n\nThe contents of an online store order shipment: which basket item goes into the shipment and in what quantity.\n\nBitrix24 API: `sale.shipmentitem.*`\nScope: `sale`\n\n## Operations\n\n- [Create a shipment item](.\u002Fshipment-items\u002Fcreate.md) — `POST \u002Fv1\u002Fshipment-items`\n- [List shipment items](.\u002Fshipment-items\u002Flist.md) — `GET \u002Fv1\u002Fshipment-items`\n- [Get a shipment item](.\u002Fshipment-items\u002Fget.md) — `GET \u002Fv1\u002Fshipment-items\u002F:id`\n- [Update a shipment item](.\u002Fshipment-items\u002Fupdate.md) — `PATCH \u002Fv1\u002Fshipment-items\u002F:id`\n- [Delete a shipment item](.\u002Fshipment-items\u002Fdelete.md) — `DELETE \u002Fv1\u002Fshipment-items\u002F:id`\n- [Search shipment items](.\u002Fshipment-items\u002Fsearch.md) — `POST \u002Fv1\u002Fshipment-items\u002Fsearch`\n- [Shipment item fields](.\u002Fshipment-items\u002Ffields.md) — `GET \u002Fv1\u002Fshipment-items\u002Ffields`\n- [Aggregate shipment items](.\u002Fshipment-items\u002Faggregate.md) — `POST \u002Fv1\u002Fshipment-items\u002Faggregate`\n- [Batch operations on shipment items](.\u002Fshipment-items\u002Fbatch.md) — `POST \u002Fv1\u002Fshipment-items\u002Fbatch`\n\n## Key fields\n\n| Field | Type | Description |\n|------|-----|---------|\n| `orderDeliveryId` | number | Shipment ID. List: [`GET \u002Fv1\u002Fshipments`](\u002Fdocs\u002Fentities\u002Fshipments\u002Flist). Set only on creation |\n| `basketId` | number | ID of a basket item of the same order. List: [`GET \u002Fv1\u002Fbasket-items`](\u002Fdocs\u002Fentities\u002Fbasket-items\u002Flist). Set only on creation |\n| `quantity` | number | Quantity of the product in the shipment, fractional values allowed |\n| `reservedQuantity` | number | Reserved quantity, read-only |\n| `xmlId` | string | External code of the item |\n\nFull list of fields — [`GET \u002Fv1\u002Fshipment-items\u002Ffields`](.\u002Fshipment-items\u002Ffields.md).\n\n## What to know before you start\n\n1. **The unallocated basket remainder sits in the system shipment.** Every basket item has a row in the order's system shipment. Creating an item in a regular shipment reduces the quantity in the system row, and deleting it returns the quantity to that row. A quantity above the remainder is rejected with `422 BITRIX_ERROR`. The system shipment is not returned by [`GET \u002Fv1\u002Fshipments\u002F:id`](\u002Fdocs\u002Fentities\u002Fshipments\u002Fget), but its items appear in the item list. A system shipment item cannot be changed directly: the remainder changes only through items of regular shipments.\n2. **The shipment and the basket item are set only on creation.** Creation requires `orderDeliveryId`, `basketId` and `quantity`, and the shipment and the basket item belong to the same order. A basket item goes into a shipment as a single row: a repeated `basketId` and `orderDeliveryId` pair is rejected. To move an item to another shipment, delete it and create it again.\n3. **`quantity` is required in every update.** [`PATCH \u002Fv1\u002Fshipment-items\u002F:id`](.\u002Fshipment-items\u002Fupdate.md) without `quantity` is rejected with `422 BITRIX_ERROR`, even if only `xmlId` changes.\n4. **Not every list row can be fetched by `id`.** Items of the system shipment and items of shipments that no longer exist are returned by [`GET \u002Fv1\u002Fshipment-items`](.\u002Fshipment-items\u002Flist.md), but [`GET \u002Fv1\u002Fshipment-items\u002F:id`](.\u002Fshipment-items\u002Fget.md) returns `404 ENTITY_NOT_FOUND` for them. To get the contents of a specific shipment, filter by `filter[orderDeliveryId]`.\n\n## Typical scenario\n\n1. Find the order: [`GET \u002Fv1\u002Forders`](\u002Fdocs\u002Fentities\u002Forders\u002Flist).\n2. Find the order's basket items: [`GET \u002Fv1\u002Fbasket-items?filter[orderId]=1027`](\u002Fdocs\u002Fentities\u002Fbasket-items\u002Flist).\n3. Create a shipment or pick an existing one: [`POST \u002Fv1\u002Fshipments`](\u002Fdocs\u002Fentities\u002Fshipments\u002Fcreate).\n4. Add a basket item to the shipment: [`POST \u002Fv1\u002Fshipment-items`](.\u002Fshipment-items\u002Fcreate.md) with `orderDeliveryId`, `basketId` and `quantity`.\n5. Check the shipment contents: [`GET \u002Fv1\u002Fshipment-items?filter[orderDeliveryId]=1207`](.\u002Fshipment-items\u002Flist.md).\n6. Change the quantity: [`PATCH \u002Fv1\u002Fshipment-items\u002F:id`](.\u002Fshipment-items\u002Fupdate.md), or remove the item: [`DELETE \u002Fv1\u002Fshipment-items\u002F:id`](.\u002Fshipment-items\u002Fdelete.md).\n\n## Limits\n\n| Limit | Value |\n|-------|----------|\n| Records per list request | up to 5000 (`limit`), 50 by default |\n| Aggregation | functions `count`, `sum`, `avg`, `min`, `max` in [`POST \u002Fv1\u002Fshipment-items\u002Faggregate`](.\u002Fshipment-items\u002Faggregate.md) |\n| Batch operations | create, update and delete in [`POST \u002Fv1\u002Fshipment-items\u002Fbatch`](.\u002Fshipment-items\u002Fbatch.md) |\n| Request rate | shared across the Vibecode API — see [Limits and optimization](\u002Fdocs\u002Foptimization) |\n\n## See also\n\n- [Shipments](\u002Fdocs\u002Fentities\u002Fshipments)\n- [Basket items](\u002Fdocs\u002Fentities\u002Fbasket-items)\n- [Orders](\u002Fdocs\u002Fentities\u002Forders)\n- [CRM deliveries](\u002Fdocs\u002Fentities\u002Fcrm-deliveries)\n- [Entity reference](\u002Fdocs\u002Fentity-api)\n","2026-10-07",{"shipment-items\u002Fcreate.md":7,"shipment-items\u002Flist.md":8,"shipment-items\u002Fget.md":9,"shipment-items\u002Fupdate.md":10,"shipment-items\u002Fdelete.md":11,"shipment-items\u002Fsearch.md":12,"shipment-items\u002Ffields.md":13,"shipment-items\u002Faggregate.md":14,"shipment-items\u002Fbatch.md":15},"## Create a shipment item\n\n`POST \u002Fv1\u002Fshipment-items`\n\nAdds a basket item of an online store order to a shipment in the specified quantity.\n\nFields are passed flat at the JSON root, without a `fields` wrapper. For where the available quantity of a basket item comes from, see [Shipment items](\u002Fdocs\u002Fentities\u002Fshipment-items).\n\n## Request fields (body)\n\n| Field | Type | Required | Description |\n|------|-----|:-----:|---------|\n| `orderDeliveryId` | number | yes | Shipment ID. List: [`GET \u002Fv1\u002Fshipments`](\u002Fdocs\u002Fentities\u002Fshipments\u002Flist). Cannot be changed after creation |\n| `basketId` | number | yes | ID of a basket item from the same order the shipment belongs to. List: [`GET \u002Fv1\u002Fbasket-items`](\u002Fdocs\u002Fentities\u002Fbasket-items\u002Flist). Cannot be changed after creation |\n| `quantity` | number | yes | Quantity of the product in the shipment. A fractional value, such as `0.5`, is stored without rounding. A number passed as a string with a dot, such as `\"0.5\"`, is also accepted. Must not exceed the available quantity of the basket item |\n| `xmlId` | string | no | External code. If omitted, it is generated automatically |\n\nFull list of fields — [`GET \u002Fv1\u002Fshipment-items\u002Ffields`](.\u002Ffields.md).\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fshipment-items\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"orderDeliveryId\": 1207,\n    \"basketId\": 1387,\n    \"quantity\": 0.5\n  }'\n```\n\n### curl — OAuth application\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fshipment-items\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"orderDeliveryId\": 1207,\n    \"basketId\": 1387,\n    \"quantity\": 0.5\n  }'\n```\n\n### JavaScript — personal key\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fshipment-items', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({\n    orderDeliveryId: 1207,\n    basketId: 1387,\n    quantity: 0.5,\n  }),\n})\n\nconst { success, data } = await res.json()\nconsole.log('Shipment item ID:', data.id)\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fshipment-items', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({\n    orderDeliveryId: 1207,\n    basketId: 1387,\n    quantity: 0.5,\n  }),\n})\n\nconst { success, data } = await res.json()\n```\n\n## Response fields\n\n| Field | Type | Description |\n|------|-----|---------|\n| `success` | boolean | `true` on success. The response HTTP status is `201` |\n| `data` | object | The created shipment item |\n| `data.id` | number | ID of the created shipment item |\n| `data.orderDeliveryId` | number | Shipment ID |\n| `data.basketId` | number | Basket item ID |\n| `data.quantity` | number | Quantity of the product in the shipment |\n| `data.reservedQuantity` | number | Reserved quantity |\n| `data.xmlId` | string | External code. If not passed in the request, a generated value such as `bx_6ac608ffa0d41` |\n| `data.dateInsert` | datetime | Creation date, ISO 8601 |\n\n## Response example\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"basketId\": 1387,\n    \"dateInsert\": \"2026-10-07T09:55:27.000Z\",\n    \"id\": 1353,\n    \"orderDeliveryId\": 1207,\n    \"quantity\": 0.5,\n    \"reservedQuantity\": 0,\n    \"xmlId\": \"bx_6ac608ffa0d41\"\n  }\n}\n```\n\n## Error response example\n\n422 — `quantity` exceeds the available quantity of the basket item:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"BITRIX_ERROR\",\n    \"message\": \"The basket does not have enough available quantity of the product \\\"product\\\" to add to the shipment. You may have already added part of this product from this order to other shipments\",\n    \"b24Code\": \"SALE_SHIPMENT_ITEM_LESS_AVAILABLE_QUANTITY\"\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|------|-----|---------|\n| 400 | `MISSING_REQUIRED_FIELDS` | A required field is missing or empty. Fields are checked in the order `orderDeliveryId`, `basketId`, `quantity`, and `message` contains the name of the first missing one |\n| 400 | `NESTED_FIELDS_ENVELOPE` | The body contains an object under `fields` instead of flat fields at the JSON root; the item is not created |\n| 400 | `READONLY_FIELD` | The body contains a read-only field, such as `reservedQuantity`. The field name is in `message` |\n| 400 | `INVALID_PARAMS` | A field value does not match its type, such as the string `\"abc\"` in the numeric `quantity`. The field name is in `message` |\n| 422 | `BITRIX_ERROR` | `quantity` exceeds the available quantity of the basket item, `b24Code` is `SALE_SHIPMENT_ITEM_LESS_AVAILABLE_QUANTITY` |\n| 422 | `BITRIX_ERROR` | The basket item is already in this shipment — `Duplicate entry for key [basketId, orderDeliveryId]`. Change the quantity of the existing item with [`PATCH \u002Fv1\u002Fshipment-items\u002F:id`](.\u002Fupdate.md) |\n| 422 | `BITRIX_ERROR` | No shipment with this `orderDeliveryId` exists, or the basket item `basketId` belongs to a different order — `shipment not exists`, `b24Code` is `201240400002` |\n| 422 | `BITRIX_ERROR` | No basket item with this `basketId` exists — `shipment not exists`, `b24Code` is `201240400003` |\n| 422 | `BITRIX_ERROR` | Bitrix24 rejected the creation for another reason. The reason text is in `message` |\n| 403 | `BITRIX_ACCESS_DENIED` | The key's user has no permission to edit orders in Bitrix24 |\n| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key is in read-only mode |\n| 403 | `SCOPE_DENIED` | The API key does not have the `sale` scope |\n| 403 | `MANAGEMENT_KEY_NO_ENTITY_ACCESS` | The request was made with a management key. Entities require an application key or a personal key with the `sale` scope |\n| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |\n| 401 | `INVALID_API_KEY` | The provided API key was not found |\n| 401 | `TOKEN_MISSING` | The API key has no configured tokens |\n\nFull list of common API errors — [Errors](\u002Fdocs\u002Ferrors).\n\n## Known specifics\n\n**An unknown scalar field name is not rejected.** An unknown scalar field passes validation without a `400`, is not saved and produces no warning. An object under `fields` is a separate case: it is rejected with `400 NESTED_FIELDS_ENVELOPE` before creation. Pass shipment item fields at the JSON root.\n\n## See also\n\n- [Shipment items](\u002Fdocs\u002Fentities\u002Fshipment-items)\n- [List shipment items](.\u002Flist.md)\n- [Get a shipment item](.\u002Fget.md)\n- [Update a shipment item](.\u002Fupdate.md)\n- [Delete a shipment item](.\u002Fdelete.md)\n- [Shipment item fields](.\u002Ffields.md)\n- [Shipments](\u002Fdocs\u002Fentities\u002Fshipments)\n- [Basket items](\u002Fdocs\u002Fentities\u002Fbasket-items)\n","## List shipment items\n\n`GET \u002Fv1\u002Fshipment-items`\n\nReturns a list of online store order shipment items with filtering, sorting and automatic pagination.\n\n## Parameters\n\n| Parameter | Type | Default | Description |\n|----------|-----|-----------|---------|\n| `limit` (query) | number | `50` | Number of records, from 1 to 5000. A value above 5000 is capped at 5000 without an error |\n| `offset` (query) | number | `0` | Skip N records: `offset=7` starts the selection at the 8th record |\n| `select` (query) | string | — | Comma-separated fields to return: `?select=id,orderDeliveryId,quantity`. An unknown field does not cause an error: it is absent from the `data` items, and `meta.warnings` carries an `UNKNOWN_SELECT_FIELD` warning with the field name in `field` |\n| `sort` (query) | string | — | Sort using shorthand syntax: `?sort=-id`. A minus sign indicates descending order |\n| `order` (query) | object | — | Sorting: `?order[id]=desc` |\n| `filter` (query) | object | — | Filtering by the fields of `GET \u002Fv1\u002Fshipment-items\u002Ffields`.\u003Cbr>[Filtering syntax](\u002Fdocs\u002Ffiltering). Example: `?filter[orderDeliveryId]=1207` |\n| `withTotal` (query) | string | — | Whether to return the record count in `meta.total`: `true` or `false`. Details — [Paging and record counts](\u002Fdocs\u002Fentity-api#paging-and-record-counts) |\n\n**Pagination.** With `limit > 50`, Vibecode assembles the response from several sequential reads of 50 records each and returns all records in one response. `meta.hasMore` shows whether more records remain.\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl -g \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fshipment-items?filter[basketId]=1387\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\"\n```\n\n### curl — OAuth application\n\n```bash\ncurl -g \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fshipment-items?filter[basketId]=1387\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\"\n```\n\n### JavaScript — personal key\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fshipment-items?filter[basketId]=1387', {\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n  },\n})\n\nconst { success, data, meta } = await res.json()\nconst total = data.reduce((sum, item) => sum + item.quantity, 0)\nconsole.log(`Basket item is split across ${data.length} shipments, ${total} in total`)\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fshipment-items?filter[basketId]=1387', {\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n  },\n})\n\nconst { success, data, meta } = await res.json()\n```\n\n## Response fields\n\n| Field | Type | Description |\n|------|-----|---------|\n| `success` | boolean | Always `true` on success |\n| `data` | array | Array of shipment items |\n| `data[].id` | number | Shipment item ID |\n| `data[].orderDeliveryId` | number | Shipment ID. List: [`GET \u002Fv1\u002Fshipments`](\u002Fdocs\u002Fentities\u002Fshipments\u002Flist) |\n| `data[].basketId` | number | Basket item ID. List: [`GET \u002Fv1\u002Fbasket-items`](\u002Fdocs\u002Fentities\u002Fbasket-items\u002Flist) |\n| `data[].quantity` | number | Product quantity in the shipment, can be fractional |\n| `data[].reservedQuantity` | number | Reserved quantity |\n| `data[].xmlId` | string | External item code |\n| `data[].dateInsert` | datetime | Creation date, ISO 8601 |\n| `meta.total` | number | Total number of records matching the filter. May be absent — see the `withTotal` parameter |\n| `meta.hasMore` | boolean | Whether more records exist beyond `limit` |\n| `meta.warnings` | array | Warnings about request parameters: `code`, `message`, `field`. Present only when there are warnings |\n| `meta.pageErrorSample` | object | Code and text of the error that stopped automatic pagination early. `data` then contains the records up to the stopping point |\n\n## Response example\n\n```json\n{\n  \"success\": true,\n  \"data\": [\n    {\n      \"basketId\": 1387,\n      \"dateInsert\": \"2026-10-04T22:01:08.000Z\",\n      \"id\": 1347,\n      \"orderDeliveryId\": 1195,\n      \"quantity\": 0.25,\n      \"reservedQuantity\": 0,\n      \"xmlId\": \"bx_6ac2be9427875\"\n    },\n    {\n      \"basketId\": 1387,\n      \"dateInsert\": \"2026-10-07T09:55:27.000Z\",\n      \"id\": 1353,\n      \"orderDeliveryId\": 1207,\n      \"quantity\": 0.75,\n      \"reservedQuantity\": 0,\n      \"xmlId\": \"vibe-doc-si-1\"\n    }\n  ],\n  \"meta\": {\n    \"total\": 2,\n    \"hasMore\": false\n  }\n}\n```\n\n## Error response example\n\n400 — filter by a nonexistent field:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"UNKNOWN_FILTER_FIELD\",\n    \"message\": \"Unknown filter field 'foo' for entity 'shipment-items'. Available: basketId, dateInsert, id, orderDeliveryId, quantity, reservedQuantity, xmlId\"\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|------|-----|---------|\n| 400 | `UNKNOWN_FILTER_FIELD` | Filter by a field that is not in the schema. Field list: [`GET \u002Fv1\u002Fshipment-items\u002Ffields`](\u002Fdocs\u002Fentities\u002Fshipment-items\u002Ffields) |\n| 400 | `INVALID_FILTER_FIELD` | The field name in the filter starts with the unsupported prefix `@` or `!@` |\n| 400 | `INVALID_FILTER_OPERATOR` | Unknown filter operator, an empty object as a condition value, or the logical condition `$or` |\n| 400 | `INVALID_FILTER` | The `filter` parameter is neither an object nor a JSON string, or both filter notations are mixed in one request |\n| 400 | `INVALID_DUPLICATE_FILTER_FIELD` | Two filter conditions reduce to the same Bitrix24 condition, for example `$ne` and `!=` on one field. Pass only one of them |\n| 400 | `UNKNOWN_SORT_FIELD` | Sorting by a field that is not in the schema |\n| 400 | `INVALID_SORT_DIRECTION` | The direction in `order` or in the object form of `sort` is not one of `asc`, `desc`, `ASC`, `DESC`, `1`, `-1` |\n| 403 | `SCOPE_DENIED` | The API key does not have the `sale` scope |\n| 403 | `MANAGEMENT_KEY_NO_ENTITY_ACCESS` | The request was made with a management key. Entities require an application key or a personal key with the `sale` scope |\n| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |\n| 401 | `INVALID_API_KEY` | The API key was not found |\n| 401 | `TOKEN_MISSING` | The API key has no configured tokens |\n| 429 | `RATE_LIMITED` | Rate limit exceeded: 300 requests per minute per portal. All API keys of the portal share one limit. The current limit is returned in the `x-ratelimit-limit` header. Retry after the delay in the `Retry-After` header |\n\nFor the full list of common API errors, see [Errors](\u002Fdocs\u002Ferrors).\n\n## Known specifics\n\n**The selection includes rows of the system shipment.** A filter by `basketId` returns all shipments the basket item is distributed across, including the system shipment holding the undistributed remainder. In the example above, basket item 1387 with quantity 1 is split into 0.75 in shipment 1207 and 0.25 in system shipment 1195. Details — [What to know before you start](\u002Fdocs\u002Fentities\u002Fshipment-items#what-to-know-before-you-start).\n\n**Not every item in the list can be retrieved by `id`.** Items of the system shipment and items of shipments that no longer exist appear in the list, but [`GET \u002Fv1\u002Fshipment-items\u002F:id`](\u002Fdocs\u002Fentities\u002Fshipment-items\u002Fget) returns `404` for them. In the example above, item 1347 gets this response. To get the contents of a specific shipment, use this list with `filter[orderDeliveryId]`.\n\n**When to use `search` instead of `list`:** [`POST \u002Fv1\u002Fshipment-items\u002Fsearch`](\u002Fdocs\u002Fentities\u002Fshipment-items\u002Fsearch) passes parameters in the request body rather than the query string, and splits the selection into time windows when filtering by a `dateInsert` range wider than 14 days.\n\n## See also\n\n- [Search shipment items](\u002Fdocs\u002Fentities\u002Fshipment-items\u002Fsearch)\n- [Get a shipment item](\u002Fdocs\u002Fentities\u002Fshipment-items\u002Fget)\n- [Create a shipment item](\u002Fdocs\u002Fentities\u002Fshipment-items\u002Fcreate)\n- [Shipment item fields](\u002Fdocs\u002Fentities\u002Fshipment-items\u002Ffields)\n- [Shipment items](\u002Fdocs\u002Fentities\u002Fshipment-items)\n- [Shipments](\u002Fdocs\u002Fentities\u002Fshipments)\n- [Filtering syntax](\u002Fdocs\u002Ffiltering)\n- [Entity reference](\u002Fdocs\u002Fentity-api)\n- [Limits and optimization](\u002Fdocs\u002Foptimization)\n","## Get a shipment item\n\n`GET \u002Fv1\u002Fshipment-items\u002F:id`\n\nReturns a single shipment item of an online store order by its ID, taken from the shipment item list or search.\n\n## Parameters\n\n| Parameter | Type | Required | Description |\n|----------|-----|:-----:|---------|\n| `id` (path) | number | yes | Shipment item ID. List: [`GET \u002Fv1\u002Fshipment-items`](\u002Fdocs\u002Fentities\u002Fshipment-items\u002Flist) |\n| `select` (query) | string | no | Comma-separated field selection: `?select=id,orderDeliveryId,quantity`. Only the listed fields are returned in `data`. An unknown field does not cause an error: it is absent from `data`, and `meta.warnings` carries an `UNKNOWN_SELECT_FIELD` warning with the field name in `field`. Field list: [`GET \u002Fv1\u002Fshipment-items\u002Ffields`](\u002Fdocs\u002Fentities\u002Fshipment-items\u002Ffields) |\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fshipment-items\u002F1353\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\"\n```\n\n### curl — OAuth application\n\n```bash\ncurl \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fshipment-items\u002F1353\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\"\n```\n\n### JavaScript — personal key\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fshipment-items\u002F1353', {\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n  },\n})\n\nconst { success, data } = await res.json()\nconsole.log(`Shipment ${data.orderDeliveryId}: basket item ${data.basketId}, quantity ${data.quantity}`)\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fshipment-items\u002F1353', {\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n  },\n})\n\nconst { success, data } = await res.json()\n```\n\n## Response fields\n\n| Field | Type | Description |\n|------|-----|---------|\n| `success` | boolean | Always `true` on success |\n| `data` | object | The shipment item |\n| `data.id` | number | Shipment item ID |\n| `data.orderDeliveryId` | number | Shipment ID. Get the shipment: [`GET \u002Fv1\u002Fshipments\u002F:id`](\u002Fdocs\u002Fentities\u002Fshipments\u002Fget) |\n| `data.basketId` | number | Basket item ID. Get the basket item: [`GET \u002Fv1\u002Fbasket-items\u002F:id`](\u002Fdocs\u002Fentities\u002Fbasket-items\u002Fget) |\n| `data.quantity` | number | Product quantity in the shipment, can be fractional |\n| `data.reservedQuantity` | number | Reserved quantity |\n| `data.xmlId` | string | External item code |\n| `data.dateInsert` | datetime | Creation date, ISO 8601 |\n| `meta.warnings` | array | Warnings about request parameters: `code`, `message`, `field`. Present only when there are warnings |\n\n## Response example\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"basketId\": 1387,\n    \"dateInsert\": \"2026-10-07T09:55:27.000Z\",\n    \"id\": 1353,\n    \"orderDeliveryId\": 1207,\n    \"quantity\": 0.75,\n    \"reservedQuantity\": 0,\n    \"xmlId\": \"vibe-doc-si-1\"\n  }\n}\n```\n\n## Error response example\n\n404 — shipment item not found:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"ENTITY_NOT_FOUND\",\n    \"message\": \"shipment item is not exists\"\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|------|-----|---------|\n| 400 | `INVALID_PARAMS` | `id` is not a non-negative integer |\n| 404 | `ENTITY_NOT_FOUND` | No shipment item with this `id` exists. Error text: `shipment item is not exists` |\n| 404 | `ENTITY_NOT_FOUND` | The request completed, but the response contains no item. This is the response for an item of a system shipment and for an item of a shipment that no longer exists. Error text: `shipmentItem \u003Cid> not found` |\n| 403 | `SCOPE_DENIED` | The API key does not have the `sale` scope |\n| 403 | `MANAGEMENT_KEY_NO_ENTITY_ACCESS` | The request was made with a management key. Entities require an application key or a personal key with the `sale` scope |\n| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |\n| 401 | `INVALID_API_KEY` | The provided API key was not found |\n| 401 | `TOKEN_MISSING` | The API key has no configured tokens |\n\nFull list of common API errors — [Errors](\u002Fdocs\u002Ferrors).\n\n## Known specifics\n\n**An item from the list may not be retrievable by `id`.** Items for which this method returns `404` with the text `shipmentItem \u003Cid> not found` are still returned by the [`GET \u002Fv1\u002Fshipment-items`](\u002Fdocs\u002Fentities\u002Fshipment-items\u002Flist) list. Get the contents of a shipment from the list with `filter[orderDeliveryId]`: it returns such items too.\n\n## See also\n\n- [List shipment items](\u002Fdocs\u002Fentities\u002Fshipment-items\u002Flist)\n- [Search shipment items](\u002Fdocs\u002Fentities\u002Fshipment-items\u002Fsearch)\n- [Update a shipment item](\u002Fdocs\u002Fentities\u002Fshipment-items\u002Fupdate)\n- [Delete a shipment item](\u002Fdocs\u002Fentities\u002Fshipment-items\u002Fdelete)\n- [Shipment item fields](\u002Fdocs\u002Fentities\u002Fshipment-items\u002Ffields)\n- [Shipment items](\u002Fdocs\u002Fentities\u002Fshipment-items)\n- [Get a shipment](\u002Fdocs\u002Fentities\u002Fshipments\u002Fget)\n","## Update a shipment item\n\n`PATCH \u002Fv1\u002Fshipment-items\u002F:id`\n\nChanges the product quantity and the external code of a shipment item in an online store order.\n\nFields are passed flat at the JSON root, without a `fields` wrapper. How a quantity change affects the free quantity of the basket item is described in [Shipment items](\u002Fdocs\u002Fentities\u002Fshipment-items).\n\n## Parameters\n\n| Parameter | Type | Required | Description |\n|----------|-----|:-----:|---------|\n| `id` (path) | number | yes | Shipment item ID, a non-negative integer. List: [`GET \u002Fv1\u002Fshipment-items`](.\u002Flist.md) |\n\n## Request fields (body)\n\n| Field | Type | Required | Description |\n|------|-----|:-----:|---------|\n| `quantity` | number | yes | New product quantity in the shipment. Pass it in every request, including when only `xmlId` changes. A fractional value is stored without rounding. A numeric string with a decimal point is also accepted, for example `\"0.5\"`. An increase is limited by the free quantity of the basket item |\n| `xmlId` | string | no | External code |\n| `orderDeliveryId` | number | no | RO. Set only on [creation](.\u002Fcreate.md). To move the item to another shipment, delete it and create it again |\n| `basketId` | number | no | RO. Set only on [creation](.\u002Fcreate.md) |\n| `reservedQuantity` | number | no | RO. Reserved quantity |\n\nFull list of fields: [`GET \u002Fv1\u002Fshipment-items\u002Ffields`](.\u002Ffields.md).\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl -X PATCH \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fshipment-items\u002F1353\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"quantity\": 0.75,\n    \"xmlId\": \"vibe-doc-si-1\"\n  }'\n```\n\n### curl — OAuth application\n\n```bash\ncurl -X PATCH \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fshipment-items\u002F1353\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"quantity\": 0.75,\n    \"xmlId\": \"vibe-doc-si-1\"\n  }'\n```\n\n### JavaScript — personal key\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fshipment-items\u002F1353', {\n  method: 'PATCH',\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({\n    quantity: 0.75,\n    xmlId: 'vibe-doc-si-1',\n  }),\n})\n\nconst { success, data } = await res.json()\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fshipment-items\u002F1353', {\n  method: 'PATCH',\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({\n    quantity: 0.75,\n    xmlId: 'vibe-doc-si-1',\n  }),\n})\n\nconst { success, data } = await res.json()\n```\n\n## Response fields\n\n| Field | Type | Description |\n|------|-----|---------|\n| `success` | boolean | `true` on success |\n| `data` | object | The updated shipment item with all fields |\n| `data.id` | number | Shipment item ID |\n| `data.orderDeliveryId` | number | Shipment ID |\n| `data.basketId` | number | Basket item ID |\n| `data.quantity` | number | Product quantity in the shipment after the change |\n| `data.reservedQuantity` | number | Reserved quantity |\n| `data.xmlId` | string | External code |\n| `data.dateInsert` | datetime | Creation date, ISO 8601 |\n\n## Response example\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"basketId\": 1387,\n    \"dateInsert\": \"2026-10-07T09:55:27.000Z\",\n    \"id\": 1353,\n    \"orderDeliveryId\": 1207,\n    \"quantity\": 0.75,\n    \"reservedQuantity\": 0,\n    \"xmlId\": \"vibe-doc-si-1\"\n  }\n}\n```\n\n## Error response example\n\n404 — no shipment item with this `id`:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"ENTITY_NOT_FOUND\",\n    \"message\": \"shipment item is not exists\"\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|------|-----|---------|\n| 400 | `READONLY_FIELD` | The body contains a read-only field: `orderDeliveryId`, `basketId`, `reservedQuantity`, `id` and others. The field name is in `message` |\n| 400 | `EMPTY_UPDATE_BODY` | The request body is empty or is not a JSON object |\n| 400 | `INVALID_PARAMS` | A field value does not match its type, for example the string `\"abc\"` in the numeric `quantity`. The field name is in `message` |\n| 400 | `INVALID_PARAMS` | `id` in the path is not a non-negative integer |\n| 404 | `ENTITY_NOT_FOUND` | No shipment item with this `id`: `shipment item is not exists` |\n| 404 | `ENTITY_NOT_FOUND` | The item belongs to the system shipment, and the passed `quantity` equals the current one. The change is not saved: `shipmentItem \u003Cid> not found` |\n| 422 | `BITRIX_ERROR` | The item belongs to the system shipment, and a new `quantity` is passed. The change is not saved: `System shipment cannot be modified`, `b24Code` is `150` |\n| 422 | `BITRIX_ERROR` | The body has no `quantity`, for example only `xmlId` or only a field with an unknown name is passed: `Required fields: quantity` |\n| 422 | `BITRIX_ERROR` | The new `quantity` exceeds the quantity available to the basket item, `b24Code` is `SALE_SHIPMENT_ITEM_LESS_AVAILABLE_QUANTITY` |\n| 422 | `BITRIX_ERROR` | Bitrix24 rejected the change for another reason. The reason is in `message` |\n| 403 | `BITRIX_ACCESS_DENIED` | The key's user has no permission to modify orders in Bitrix24 |\n| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key works in read-only mode |\n| 403 | `SCOPE_DENIED` | The API key does not have the `sale` scope |\n| 403 | `MANAGEMENT_KEY_NO_ENTITY_ACCESS` | The request is made with a management key. Entities require an application key or a personal key with the `sale` scope |\n| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is not passed |\n| 401 | `INVALID_API_KEY` | The passed API key is not found |\n| 401 | `TOKEN_MISSING` | The API key has no configured tokens |\n\nFull list of common API errors: [Errors](\u002Fdocs\u002Ferrors).\n\n## See also\n\n- [Shipment items](\u002Fdocs\u002Fentities\u002Fshipment-items)\n- [Get a shipment item](.\u002Fget.md)\n- [Create a shipment item](.\u002Fcreate.md)\n- [Delete a shipment item](.\u002Fdelete.md)\n- [Shipment item fields](.\u002Ffields.md)\n- [Shipments](\u002Fdocs\u002Fentities\u002Fshipments)\n- [Basket items](\u002Fdocs\u002Fentities\u002Fbasket-items)\n","## Delete a shipment item\n\n`DELETE \u002Fv1\u002Fshipment-items\u002F:id`\n\nDeletes an item from an online store order shipment by ID. A deleted shipment item cannot be restored through the API — create a new one if needed.\n\nWhere the quantity of the deleted item is returned is described in [Shipment items](\u002Fdocs\u002Fentities\u002Fshipment-items).\n\n## Parameters\n\n| Parameter | Type | Required | Description |\n|----------|-----|:-----:|---------|\n| `id` (path) | number | yes | Shipment item ID, a non-negative integer. List: [`GET \u002Fv1\u002Fshipment-items`](.\u002Flist.md) |\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl -X DELETE \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fshipment-items\u002F1353\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\"\n```\n\n### curl — OAuth application\n\n```bash\ncurl -X DELETE \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fshipment-items\u002F1353\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\"\n```\n\n### JavaScript — personal key\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fshipment-items\u002F1353', {\n  method: 'DELETE',\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n  },\n})\n\nif (res.status === 204) {\n  console.log('Shipment item deleted')\n}\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fshipment-items\u002F1353', {\n  method: 'DELETE',\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n  },\n})\n\nif (res.status === 204) {\n  console.log('Shipment item deleted')\n}\n```\n\n## Response\n\nOn successful deletion, the API returns HTTP status `204 No Content` with an empty body. Success is indicated by the status code, not by the body.\n\n## Response example\n\n```http\nHTTP\u002F1.1 204 No Content\n```\n\n## Error response example\n\n404 — no shipment item with this `id` exists, or it has already been deleted:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"ENTITY_NOT_FOUND\",\n    \"message\": \"shipment item is not exists\"\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|------|-----|---------|\n| 400 | `INVALID_PARAMS` | `id` in the path is not a non-negative integer. Error text — `id must be a non-negative integer` |\n| 404 | `ENTITY_NOT_FOUND` | No shipment item with this `id` exists, or it has already been deleted. Error text — `shipment item is not exists` |\n| 422 | `BITRIX_ERROR` | Bitrix24 rejected the deletion. The reason is in `message` |\n| 403 | `BITRIX_ACCESS_DENIED` | The key's user has no permission to modify orders in Bitrix24 |\n| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key is in read-only mode |\n| 403 | `SCOPE_DENIED` | The API key does not have the `sale` scope |\n| 403 | `MANAGEMENT_KEY_NO_ENTITY_ACCESS` | The request was made with a management key. Entities require an application key or a personal key with the `sale` scope |\n| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |\n| 401 | `INVALID_API_KEY` | The provided API key was not found |\n| 401 | `TOKEN_MISSING` | The API key has no configured tokens |\n\nFull list of common API errors — [Errors](\u002Fdocs\u002Ferrors).\n\n## See also\n\n- [Shipment items](\u002Fdocs\u002Fentities\u002Fshipment-items)\n- [Create a shipment item](.\u002Fcreate.md)\n- [Get a shipment item](.\u002Fget.md)\n- [List shipment items](.\u002Flist.md)\n- [Shipments](\u002Fdocs\u002Fentities\u002Fshipments)\n","## Search shipment items\n\n`POST \u002Fv1\u002Fshipment-items\u002Fsearch`\n\nSearches online store order shipment items with filtering, sorting, and automatic pagination. Parameters are passed in the body of the POST request. Suited to complex filters and wide date ranges. For simple selections of up to 5000 records, the shipment item list is enough.\n\n## Request fields (body)\n\n| Field | Type | Required | Default | Description |\n|------|-----|:-----:|-----------|---------|\n| `filter` | object | no | — | Filtering by the fields from `GET \u002Fv1\u002Fshipment-items\u002Ffields`.\u003Cbr>[Filtering syntax](\u002Fdocs\u002Ffiltering). Example: `{ \"basketId\": 1387 }` |\n| `select` | string[] | no | — | Field selection: `[\"id\", \"orderDeliveryId\", \"quantity\"]`. A comma-separated string is also accepted. An unknown field does not cause an error: it is absent from the `data` items, and `meta.warnings` carries an `UNKNOWN_SELECT_FIELD` warning with the field name in `field` |\n| `sort` | string | no | — | Sorting via the short syntax: `\"-id\"`, where a leading minus means descending |\n| `order` | object | no | — | Sorting as an object: `{ \"id\": \"asc\" }`. If `sort` is also passed, `sort` takes effect |\n| `limit` | number | no | `50` | Number of records, from 1 to 5000. A value above 5000 is reduced to 5000 without an error |\n| `offset` | number | no | `0` | Skip N records. Rejected when combined with a date range filter wider than 14 days, unless `autoWindow: false` is passed — see `UNSTABLE_OFFSET_PAGINATION` in the \"Errors\" section |\n| `autoWindow` | boolean | no | `true` | Split the selection into weekly windows when filtering by a `dateInsert` range wider than 14 days. `false` disables splitting |\n| `withTotal` | boolean | no | — | Whether to return the record count in `meta.total`. Details — [Paging and record counts](\u002Fdocs\u002Fentity-api#paging-and-record-counts) |\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fshipment-items\u002Fsearch\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"filter\": { \"basketId\": 1387 },\n    \"select\": [\"id\", \"orderDeliveryId\", \"quantity\"],\n    \"order\": { \"id\": \"asc\" }\n  }'\n```\n\n### curl — OAuth application\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fshipment-items\u002Fsearch\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"filter\": { \"basketId\": 1387 },\n    \"select\": [\"id\", \"orderDeliveryId\", \"quantity\"],\n    \"order\": { \"id\": \"asc\" }\n  }'\n```\n\n### JavaScript — personal key\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fshipment-items\u002Fsearch', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({\n    filter: { basketId: 1387 },\n    select: ['id', 'orderDeliveryId', 'quantity'],\n    order: { id: 'asc' },\n  }),\n})\n\nconst { success, data, meta } = await res.json()\nfor (const item of data) {\n  console.log(`Shipment ${item.orderDeliveryId}: ${item.quantity}`)\n}\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fshipment-items\u002Fsearch', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({\n    filter: { basketId: 1387 },\n    select: ['id', 'orderDeliveryId', 'quantity'],\n    order: { id: 'asc' },\n  }),\n})\n\nconst { success, data, meta } = await res.json()\n```\n\n## Response fields\n\n| Field | Type | Description |\n|------|-----|---------|\n| `success` | boolean | Always `true` on success |\n| `data` | array | Array of shipment items |\n| `data[].id` | number | Shipment item identifier |\n| `data[].orderDeliveryId` | number | Shipment ID. List: [`GET \u002Fv1\u002Fshipments`](\u002Fdocs\u002Fentities\u002Fshipments\u002Flist) |\n| `data[].basketId` | number | Basket item ID. List: [`GET \u002Fv1\u002Fbasket-items`](\u002Fdocs\u002Fentities\u002Fbasket-items\u002Flist) |\n| `data[].quantity` | number | Product quantity in the shipment; may be fractional |\n| `data[].reservedQuantity` | number | Reserved quantity |\n| `data[].xmlId` | string | External code of the item |\n| `data[].dateInsert` | datetime | Creation date, ISO 8601 |\n| `meta.total` | number | How many records matched the filter. May be absent — see the `withTotal` field |\n| `meta.hasMore` | boolean | Whether there are more records beyond `limit` |\n| `meta.durationMs` | number | Request duration in milliseconds |\n| `meta.autoWindowed` | boolean | `true` if the selection was split into time windows |\n| `meta.windowCount` | number | Number of windows. Included when `autoWindowed: true` |\n| `meta.windowErrors` | number | How many windows ended with an error. Included if some windows failed |\n| `meta.windowErrorSample` | object | Error code and message of the first failed window. Included with `windowErrors` |\n| `meta.batchWaves` | number | Number of waves of parallel requests. Included when `autoWindowed: true` |\n| `meta.warnings` | array | Warnings about request parameters: `code`, `message`, `field`. Included only when there are warnings |\n| `meta.hint` | string | Advice to narrow the date range or disable splitting. Included if the search processed more than 10 windows and took longer than 10 seconds |\n| `meta.pageErrorSample` | object | Code and message of the error that stopped automatic pagination early. Included only if `data` contains fewer records than `limit` |\n\n## Response example\n\nA request with `select` returns only the listed fields:\n\n```json\n{\n  \"success\": true,\n  \"data\": [\n    {\n      \"id\": 1347,\n      \"orderDeliveryId\": 1195,\n      \"quantity\": 0.25\n    },\n    {\n      \"id\": 1353,\n      \"orderDeliveryId\": 1207,\n      \"quantity\": 0.75\n    }\n  ],\n  \"meta\": {\n    \"total\": 2,\n    \"hasMore\": false,\n    \"durationMs\": 342\n  }\n}\n```\n\n## Error response example\n\n400 — filter by a nonexistent field:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"UNKNOWN_FILTER_FIELD\",\n    \"message\": \"Unknown filter field 'foo' for entity 'shipment-items'. Available: basketId, dateInsert, id, orderDeliveryId, quantity, reservedQuantity, xmlId\"\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|------|-----|---------|\n| 400 | `UNKNOWN_FILTER_FIELD` | Filter by a field that is not in the schema. Field list: [`GET \u002Fv1\u002Fshipment-items\u002Ffields`](\u002Fdocs\u002Fentities\u002Fshipment-items\u002Ffields) |\n| 400 | `INVALID_FILTER_FIELD` | The field name in the filter starts with the unsupported prefix `@` or `!@` |\n| 400 | `INVALID_FILTER_OPERATOR` | Unknown filter operator, an empty object as a condition value, or the logical condition `$or` |\n| 400 | `INVALID_FILTER_SHAPE` | `filter` is not an object of conditions, for example a string, number, or array |\n| 400 | `INVALID_DUPLICATE_FILTER_FIELD` | Two filter conditions reduce to one Bitrix24 condition, for example `$ne` and `!=` on the same field. Pass only one of them |\n| 400 | `UNKNOWN_SORT_FIELD` | Sorting by a field that is not in the schema |\n| 400 | `INVALID_SORT_TYPE` | `sort` or `order` has an unsupported type, for example a number |\n| 400 | `INVALID_SORT_DIRECTION` | The direction in `order` or in the object form of `sort` is not one of `asc`, `desc`, `ASC`, `DESC`, `1`, `-1` |\n| 400 | `INVALID_LIMIT` | `limit` is not a number |\n| 400 | `INVALID_SELECT_TYPE` | `select` is not a string or an array of strings |\n| 400 | `INVALID_REQUEST` | The request body is not a JSON object |\n| 400 | `UNSTABLE_OFFSET_PAGINATION` | `offset` greater than zero together with a filter by a date range wider than 14 days. Fetch everything in one request with `limit` up to 5000, or pass `autoWindow: false` with sorting by `id`, or split the date range into parts yourself |\n| 403 | `SCOPE_DENIED` | The API key does not have the `sale` scope |\n| 403 | `MANAGEMENT_KEY_NO_ENTITY_ACCESS` | The request was made with a management key. Entities require an application key or a personal key with the `sale` scope |\n| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |\n| 401 | `INVALID_API_KEY` | The API key passed was not found |\n| 401 | `TOKEN_MISSING` | The API key has no configured tokens |\n| 429 | `RATE_LIMITED` | Rate limit exceeded: 300 requests per minute per portal. All API keys of the portal share one limit. The current limit is returned in the `x-ratelimit-limit` header. Retry after the delay in the `Retry-After` header |\n\nFor the full list of common API errors, see [Errors](\u002Fdocs\u002Ferrors).\n\n## Known specifics\n\n**Splitting into time windows.** With windows, the selection gets past the cap of 5000 records per call. A range from January 1, 2025 to October 8, 2026 was split into 93 windows processed in three waves: `meta.windowCount: 93`, `meta.batchWaves: 3`. The same request with `autoWindow: false` returned the same 104 records in a single pass.\n\n**A partial window failure does not abort the request.** If some of the windows failed, the response is returned with `success: true` and records only from the successful windows. Before treating the selection as complete, check that `meta.windowErrors` is absent.\n\n## See also\n\n- [List shipment items](\u002Fdocs\u002Fentities\u002Fshipment-items\u002Flist)\n- [Get a shipment item](\u002Fdocs\u002Fentities\u002Fshipment-items\u002Fget)\n- [Shipment item aggregation](\u002Fdocs\u002Fentities\u002Fshipment-items\u002Faggregate)\n- [Shipment item fields](\u002Fdocs\u002Fentities\u002Fshipment-items\u002Ffields)\n- [Shipment items](\u002Fdocs\u002Fentities\u002Fshipment-items)\n- [Filtering syntax](\u002Fdocs\u002Ffiltering)\n- [Entity reference](\u002Fdocs\u002Fentity-api)\n- [Limits and optimization](\u002Fdocs\u002Foptimization)\n","## Shipment item fields\n\n`GET \u002Fv1\u002Fshipment-items\u002Ffields`\n\nReturns the shipment item field schema — a reference for selecting and filtering fields and for the create and update bodies.\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fshipment-items\u002Ffields\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\"\n```\n\n### curl — OAuth application\n\n```bash\ncurl \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fshipment-items\u002Ffields\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\"\n```\n\n### JavaScript — personal key\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fshipment-items\u002Ffields', {\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n  },\n})\n\nconst { data } = await res.json()\nconsole.log('Shipment item fields:', Object.keys(data.fields))\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fshipment-items\u002Ffields', {\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n  },\n})\n\nconst { data } = await res.json()\n```\n\n## Response fields\n\n| Field | Type | Description |\n|------|-----|---------|\n| `success` | boolean | Always `true` on success |\n| `data.fields` | object | Field schema. The key is the field name, the value is the field description |\n| `data.fields.\u003Cfield>.type` | string | Value type: `number`, `string`, `datetime` |\n| `data.fields.\u003Cfield>.readonly` | boolean | `true` means the field is set by the system; passing it on create or update is rejected with `400 READONLY_FIELD` |\n| `data.fields.\u003Cfield>.required` | boolean | Present only on fields required at creation, always with the value `true` |\n| `data.fields.\u003Cfield>.readonlyOnUpdate` | boolean | Present only on fields that are set at creation and cannot be changed on update, always with the value `true`. Passing such a field to [`PATCH \u002Fv1\u002Fshipment-items\u002F:id`](.\u002Fupdate.md) is rejected with `400 READONLY_FIELD` |\n| `data.fields.\u003Cfield>.label` | string | Short field name |\n| `data.fields.\u003Cfield>.description` | string | Field explanation |\n| `data.aggregatable` | array | Fields allowed in [shipment item aggregation](.\u002Faggregate.md): as the field of a numeric function and as a `groupBy` grouping field |\n| `data.batch` | array | Operations available in [batch operations on shipment items](.\u002Fbatch.md): `create`, `update`, `delete` |\n\n### Shipment item fields\n\nThe full set of fields returned by `GET \u002Fv1\u002Fshipment-items\u002Ffields`. The RO column marks read-only fields.\n\n| Field | Type | RO | Description |\n|------|-----|:--:|---------|\n| `id` | number | yes | Shipment item ID |\n| `orderDeliveryId` | number | no | Shipment ID. List: [`GET \u002Fv1\u002Fshipments`](\u002Fdocs\u002Fentities\u002Fshipments\u002Flist). Required at creation. Set only at creation: on update it is rejected with `400 READONLY_FIELD`, marked `readonlyOnUpdate` in the schema |\n| `basketId` | number | no | ID of a basket item of the same order. List: [`GET \u002Fv1\u002Fbasket-items`](\u002Fdocs\u002Fentities\u002Fbasket-items\u002Flist). Required at creation. Set only at creation: on update it is rejected with `400 READONLY_FIELD`, marked `readonlyOnUpdate` in the schema |\n| `quantity` | number | no | Quantity of the product in the shipment; fractional values are allowed, for example `0.75`. Required at creation and in every [update](.\u002Fupdate.md): a `PATCH` without `quantity` is rejected with `422 BITRIX_ERROR` |\n| `reservedQuantity` | number | yes | Reserved quantity |\n| `xmlId` | string | no | External code of the item |\n| `dateInsert` | datetime | yes | Creation date in ISO 8601 format, for example `2026-10-07T09:55:27.000Z` |\n\n## Response example\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"fields\": {\n      \"basketId\": {\n        \"type\": \"number\",\n        \"readonly\": false,\n        \"readonlyOnUpdate\": true,\n        \"required\": true,\n        \"label\": \"Basket item ID\",\n        \"description\": \"Basket item of the same order. Lookup: GET \u002Fv1\u002Fbasket-items.\"\n      },\n      \"dateInsert\": {\n        \"type\": \"datetime\",\n        \"readonly\": true,\n        \"label\": \"Creation date\",\n        \"description\": \"Creation date.\"\n      },\n      \"id\": {\n        \"type\": \"number\",\n        \"readonly\": true,\n        \"label\": \"Shipment item ID\",\n        \"description\": \"Shipment item identifier.\"\n      },\n      \"orderDeliveryId\": {\n        \"type\": \"number\",\n        \"readonly\": false,\n        \"readonlyOnUpdate\": true,\n        \"required\": true,\n        \"label\": \"Shipment ID\",\n        \"description\": \"Shipment ID. Lookup: GET \u002Fv1\u002Fshipments.\"\n      },\n      \"quantity\": {\n        \"type\": \"number\",\n        \"readonly\": false,\n        \"required\": true,\n        \"label\": \"Quantity\",\n        \"description\": \"Quantity.\"\n      },\n      \"reservedQuantity\": {\n        \"type\": \"number\",\n        \"readonly\": true,\n        \"label\": \"Reserved\",\n        \"description\": \"Reserved.\"\n      },\n      \"xmlId\": {\n        \"type\": \"string\",\n        \"readonly\": false,\n        \"label\": \"External code\",\n        \"description\": \"External code.\"\n      }\n    },\n    \"aggregatable\": [\n      \"quantity\",\n      \"reservedQuantity\",\n      \"orderDeliveryId\",\n      \"basketId\"\n    ],\n    \"batch\": [\n      \"create\",\n      \"update\",\n      \"delete\"\n    ]\n  }\n}\n```\n\n## Error response example\n\n401 — the API key is not passed:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"MISSING_API_KEY\",\n    \"message\": \"API key required. Pass via X-Api-Key header.\"\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|------|-----|---------|\n| 403 | `SCOPE_DENIED` | The API key has no `sale` scope |\n| 403 | `MANAGEMENT_KEY_NO_ENTITY_ACCESS` | The request was made with a management key. Entities require an application key or a personal key with the `sale` scope |\n| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is not passed |\n| 401 | `INVALID_API_KEY` | The passed API key was not found |\n| 401 | `TOKEN_MISSING` | The API key has no configured tokens |\n| 429 | `RATE_LIMITED` | Rate limit exceeded: 300 requests per minute per portal. All API keys of the portal share one limit. The current limit is returned in the `x-ratelimit-limit` header. Retry after the delay in the `Retry-After` header |\n\nFor the full list of common API errors, see [Errors](\u002Fdocs\u002Ferrors).\n\n## See also\n\n- [Create a shipment item](.\u002Fcreate.md)\n- [Update a shipment item](.\u002Fupdate.md)\n- [List shipment items](.\u002Flist.md)\n- [Shipment item aggregation](.\u002Faggregate.md)\n- [Batch operations on shipment items](.\u002Fbatch.md)\n- [Shipment items](\u002Fdocs\u002Fentities\u002Fshipment-items)\n- [Shipments](\u002Fdocs\u002Fentities\u002Fshipments)\n- [Basket items](\u002Fdocs\u002Fentities\u002Fbasket-items)\n- [Entity reference](\u002Fdocs\u002Fentity-api)\n","## Aggregate shipment items\n\n`POST \u002Fv1\u002Fshipment-items\u002Faggregate`\n\nCounts shipment items and computes the sum, average, minimum and maximum of the product quantity, with filtering and grouping by shipment or basket item.\n\n## Standard fields\n\n| Field | Purpose |\n|------|------------|\n| `quantity` | Product quantity in the item — the main field for `sum` \u002F `avg` \u002F `min` \u002F `max`. Also available for `groupBy` |\n| `reservedQuantity` | Reserved quantity — a numeric field for `sum` \u002F `avg` \u002F `min` \u002F `max` and `groupBy` |\n| `orderDeliveryId` | Shipment ID from [`GET \u002Fv1\u002Fshipments`](\u002Fdocs\u002Fentities\u002Fshipments\u002Flist) — used in `groupBy` to break items down by shipment |\n| `basketId` | Basket item ID from [`GET \u002Fv1\u002Fbasket-items`](\u002Fdocs\u002Fentities\u002Fbasket-items\u002Flist) — used in `groupBy` to break items down by basket product |\n\nThe fields allowed in `groupBy` are listed in the `aggregatable` array of [`GET \u002Fv1\u002Fshipment-items\u002Ffields`](.\u002Ffields.md). Numeric functions accept any field of type `number` from the same schema, including `id`, which is outside `aggregatable`.\n\n**User fields.** If you pass a nonexistent field to `sum` \u002F `avg` \u002F `min` \u002F `max`, the `400 INVALID_PARAMS` response lists the allowed numeric fields. That list contains only the standard shipment item fields — `basketId`, `id`, `orderDeliveryId`, `quantity`, `reservedQuantity`. It contains no user fields.\n\n## Request fields (body)\n\n| Field | Type | Required | Description |\n|------|-----|:-----:|---------|\n| `aggregate` | array | no | Array of expressions `{ \"field\": \"quantity\", \"function\": \"sum\" }`, up to 5 per request. Functions: `count`, `sum`, `avg`, `min`, `max`. For `count`, the field is `\"*\"`. Without the parameter, only `count` is returned |\n| `filter` | object | no | Filtering by the fields of [`GET \u002Fv1\u002Fshipment-items\u002Ffields`](.\u002Ffields.md).\u003Cbr>[Filtering syntax](\u002Fdocs\u002Ffiltering). Example: `{ \"orderDeliveryId\": 985 }` |\n| `groupBy` | string \\| string[] | no | A field or array of fields to group by, up to 5 fields. Allowed values come from the `aggregatable` array: `quantity`, `reservedQuantity`, `orderDeliveryId`, `basketId` |\n| `groupOrderBy` | array | no | Group sorting: `[{ \"field\": \"quantity:sum\", \"direction\": \"desc\" }]`. The `field` takes `count`, a field name from `groupBy`, or `\u003Cfield>:\u003Cfunction>` from `aggregate`. Works only together with `groupBy` |\n| `groupLimit` | number | no | Limit on the number of returned groups, from 1 to 1000. Works only together with `groupBy` |\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fshipment-items\u002Faggregate\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"filter\": { \"orderDeliveryId\": { \"$in\": [975, 985] } },\n    \"aggregate\": [\n      { \"field\": \"*\", \"function\": \"count\" },\n      { \"field\": \"quantity\", \"function\": \"sum\" },\n      { \"field\": \"quantity\", \"function\": \"avg\" }\n    ],\n    \"groupBy\": \"orderDeliveryId\"\n  }'\n```\n\n### curl — OAuth application\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fshipment-items\u002Faggregate\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"filter\": { \"orderDeliveryId\": { \"$in\": [975, 985] } },\n    \"aggregate\": [\n      { \"field\": \"*\", \"function\": \"count\" },\n      { \"field\": \"quantity\", \"function\": \"sum\" },\n      { \"field\": \"quantity\", \"function\": \"avg\" }\n    ],\n    \"groupBy\": \"orderDeliveryId\"\n  }'\n```\n\n### JavaScript — personal key\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fshipment-items\u002Faggregate', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({\n    filter: { orderDeliveryId: { $in: [975, 985] } },\n    aggregate: [\n      { field: '*', function: 'count' },\n      { field: 'quantity', function: 'sum' },\n      { field: 'quantity', function: 'avg' },\n    ],\n    groupBy: 'orderDeliveryId',\n  }),\n})\n\nconst { success, data } = await res.json()\n\u002F\u002F data.groups — product quantity per shipment\nconsole.log(data.groups)\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fshipment-items\u002Faggregate', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({\n    filter: { orderDeliveryId: { $in: [975, 985] } },\n    aggregate: [\n      { field: '*', function: 'count' },\n      { field: 'quantity', function: 'sum' },\n      { field: 'quantity', function: 'avg' },\n    ],\n    groupBy: 'orderDeliveryId',\n  }),\n})\n\nconst { success, data } = await res.json()\n```\n\nTo group by several fields, pass an array: `\"groupBy\": [\"orderDeliveryId\", \"basketId\"]`, up to 5 fields.\n\n## Other scenarios\n\nThe blocks below are request bodies.\n\nOnly the number of items in a shipment — without the `aggregate` array no records are loaded, and `data.meta.recordsProcessed` in the response is `0`:\n\n```json\n{ \"filter\": { \"orderDeliveryId\": 985 } }\n```\n\nShipments with the largest product quantity — the first two groups by descending sum of `quantity`:\n\n```json\n{\n  \"aggregate\": [{ \"field\": \"quantity\", \"function\": \"sum\" }],\n  \"groupBy\": \"orderDeliveryId\",\n  \"groupOrderBy\": [{ \"field\": \"quantity:sum\", \"direction\": \"desc\" }],\n  \"groupLimit\": 2\n}\n```\n\nTotal and maximum product quantity across all items, without grouping:\n\n```json\n{\n  \"aggregate\": [\n    { \"field\": \"*\", \"function\": \"count\" },\n    { \"field\": \"quantity\", \"function\": \"sum\" },\n    { \"field\": \"quantity\", \"function\": \"max\" }\n  ]\n}\n```\n\n## Response fields\n\n| Field | Type | Description |\n|------|-----|---------|\n| `success` | boolean | Always `true` on success |\n| `data.count` | number | Number of shipment items matching the filter |\n| `data.aggregates` | object | Results of numeric functions by field: `{ \"quantity\": { \"sum\": 16, \"avg\": 5.33 } }`. An empty object if `aggregate` contains only `count`: the `count` result comes in `data.count` and `data.groups[].count`, not here |\n| `data.groups` | array | Present only with `groupBy`. Each element holds the grouping field values, `count` and `aggregates` for the group |\n| `data.meta.totalRecords` | number | Total number of records matching the filter |\n| `data.meta.recordsProcessed` | number | Number of records processed, up to 5000 |\n| `data.meta.truncated` | boolean | `true` if the numbers were not computed over all records matching the filter: fewer records were read than `data.count` promised — including when more than 5000 matched the filter — or the slice was cut short by a subpage error. The shortfall is reported in `data.meta.recordsShortfall`, and the interrupted slice in `data.meta.pageErrorSample`. Always present, `false` on a complete response. If the request has neither `groupBy` nor numeric functions, no records are loaded and the flag is always `false` |\n| `data.meta.groupTotal` | number | Present only with `groupBy` — the number of groups before `groupLimit` is applied |\n| `data.meta.groupsTruncated` | boolean | Present only with `groupBy`. `true` if the group list was cut by `groupLimit` |\n\n## Response example\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"count\": 3,\n    \"aggregates\": {\n      \"quantity\": {\n        \"sum\": 16,\n        \"avg\": 5.333333333333333\n      }\n    },\n    \"groups\": [\n      {\n        \"orderDeliveryId\": 975,\n        \"count\": 1,\n        \"aggregates\": {\n          \"quantity\": {\n            \"sum\": 1,\n            \"avg\": 1\n          }\n        }\n      },\n      {\n        \"orderDeliveryId\": 985,\n        \"count\": 2,\n        \"aggregates\": {\n          \"quantity\": {\n            \"sum\": 15,\n            \"avg\": 7.5\n          }\n        }\n      }\n    ],\n    \"meta\": {\n      \"totalRecords\": 3,\n      \"recordsProcessed\": 3,\n      \"truncated\": false,\n      \"groupTotal\": 2,\n      \"groupsTruncated\": false\n    }\n  }\n}\n```\n\nWithout `groupBy`, the `data.groups`, `data.meta.groupTotal` and `data.meta.groupsTruncated` fields are absent from the response.\n\n## Error response example\n\n400 — the field is not in the schema, and the message lists the allowed numeric fields:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"INVALID_PARAMS\",\n    \"message\": \"Field 'weight' not found. Available numeric fields: basketId, id, orderDeliveryId, quantity, reservedQuantity.\"\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|------|-----|---------|\n| 400 | `INVALID_PARAMS` | `count` is passed with a field other than `\"*\"` |\n| 400 | `INVALID_PARAMS` | `aggregate` is passed as a non-array or an empty array |\n| 400 | `INVALID_PARAMS` | `aggregate` contains more than 5 expressions |\n| 400 | `INVALID_PARAMS` | Unknown function — the message lists the allowed ones |\n| 400 | `INVALID_PARAMS` | `sum` \u002F `avg` \u002F `min` \u002F `max` without a field or with the field `\"*\"` |\n| 400 | `INVALID_PARAMS` | The field for `sum` \u002F `avg` \u002F `min` \u002F `max` is not numeric, for example `xmlId` — the message names its type |\n| 400 | `INVALID_PARAMS` | The field for `sum` \u002F `avg` \u002F `min` \u002F `max` is not in the schema — the message contains the list of numeric fields |\n| 400 | `INVALID_PARAMS` | The `field` or `function` fields are passed at the top level of the body instead of the `aggregate` array |\n| 400 | `INVALID_PARAMS` | `groupBy` is neither a string nor an array of strings |\n| 400 | `INVALID_PARAMS` | A field in `groupBy` is outside the `aggregatable` array, for example `xmlId` — the message contains the list of allowed ones |\n| 400 | `INVALID_PARAMS` | `groupBy` contains more than 5 fields |\n| 400 | `INVALID_PARAMS` | `groupBy` contains a reserved name: `count`, `aggregates`, `meta`, `groups` |\n| 400 | `INVALID_PARAMS` | `groupOrderBy` or `groupLimit` is passed without `groupBy`, or the value of one of them is invalid |\n| 400 | `UNKNOWN_FILTER_FIELD` | Unknown field in `filter` — the message contains the list of shipment item fields |\n| 400 | `INVALID_FILTER_FIELD` | A field name in `filter` starts with the unsupported prefix `@` or `!@` |\n| 400 | `INVALID_FILTER_OPERATOR` | Unsupported operator in `filter` or a logical condition, for example `$or` |\n| 400 | `INVALID_FILTER_SHAPE` | `filter` is not passed as an object of conditions, for example as a string |\n| 400 | `INVALID_DUPLICATE_FILTER_FIELD` | Two filter conditions reduce to one Bitrix24 condition, for example `$ne` and `$nin` on the same field. Pass one of them |\n| 403 | `SCOPE_DENIED` | The API key lacks the `sale` scope |\n| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |\n| 401 | `TOKEN_MISSING` | The API key has no configured tokens |\n| 429 | `RATE_LIMITED` | Request limit exceeded: 300 per minute per portal, and all API keys of the portal share one limit. The current limit is returned in the `x-ratelimit-limit` header. Retry after the period in the `Retry-After` header |\n\nFor the full list of common API errors, see [Errors](\u002Fdocs\u002Ferrors).\n\n## Known specifics\n\n**`count` versus numeric functions.** A request without `groupBy` and without numeric functions runs as a single request to Bitrix24 — no records are loaded, and the response time does not depend on the number of items. As soon as the request contains `sum` \u002F `avg` \u002F `min` \u002F `max` or `groupBy`, including together with a single `count`, records are loaded page by page, at most 5000, and aggregated on the Vibecode side. With `meta.truncated: true`, the `truncated: true` marker is set both inside each field object in `data.aggregates` and on each element of `data.groups`, and `data.meta.warnings` carries the `AGGREGATE_TRUNCATED` warning. For an exact number on a large result set, use a request without `groupBy` and numeric functions, or narrow the filter, for example by `orderDeliveryId`. For full details, see [Aggregation POST — the 5000-record ceiling](\u002Fdocs\u002Fentity-api#aggregation-post-the-5000-record-ceiling).\n\n**The count includes items of the system shipment.** The selection includes the same records as the [item list](.\u002Flist.md), including items of the system shipment, which holds the unallocated remainder of the basket. Therefore, the sum of `quantity` for a basket item without a shipment filter equals the product quantity in the basket. To count only what has been shipped, filter by the `orderDeliveryId` of shipments from [`GET \u002Fv1\u002Fshipments`](\u002Fdocs\u002Fentities\u002Fshipments\u002Flist).\n\n## See also\n\n- [List shipment items](.\u002Flist.md)\n- [Search shipment items](.\u002Fsearch.md)\n- [Shipment item fields](.\u002Ffields.md)\n- [Shipment items](\u002Fdocs\u002Fentities\u002Fshipment-items)\n- [Filtering syntax](\u002Fdocs\u002Ffiltering)\n- [Limits and optimization](\u002Fdocs\u002Foptimization)\n","## Batch operations on shipment items\n\n`POST \u002Fv1\u002Fshipment-items\u002Fbatch`\n\nCreate, update, delete or read shipment items in bulk with one request — up to 500 items per write and up to 50 calls per read. This is a dedicated endpoint for this entity, not to be confused with the [universal batch](\u002Fdocs\u002Fbatch), which combines operations on different entities and is limited to 50 calls.\n\n## Request fields (body)\n\n| Field | Type | Required | Description |\n|------|-----|:-----:|---------|\n| `action` | string | yes | Batch operation: `create`, `update`, `delete` for writes, `list`, `get` for reads. One request performs one operation |\n| `items` | array | yes for `create` and `update` | List of items, up to 500 |\n| `items[].orderDeliveryId` | number | yes for `create` | Shipment ID. List: [`GET \u002Fv1\u002Fshipments`](\u002Fdocs\u002Fentities\u002Fshipments\u002Flist). Not passed in `update` — the field is read-only |\n| `items[].basketId` | number | yes for `create` | ID of a basket item of the same order. List: [`GET \u002Fv1\u002Fbasket-items`](\u002Fdocs\u002Fentities\u002Fbasket-items\u002Flist). Not passed in `update` — the field is read-only |\n| `items[].quantity` | number | yes | Product quantity in the shipment; a fractional value is stored without rounding. Required both in `create` and in every `update` item. An `update` item without `quantity` does not reject the batch — it fails inside a `200` response |\n| `items[].xmlId` | string | no | External code |\n| `items[].id` | number | yes for `update` | Shipment item ID. List: [`GET \u002Fv1\u002Fshipment-items`](.\u002Flist.md) |\n| `ids` | number[] | yes for `delete` | IDs of the shipment items to delete, up to 500. List: [`GET \u002Fv1\u002Fshipment-items`](.\u002Flist.md) |\n| `calls` | array | yes for `list` and `get` | List of read calls, up to 50. Each call is an object `{ \"params\": { … } }` |\n| `calls[].params` | object | yes | For `list` — the [item list](.\u002Flist.md) parameters: `filter`, `select`, `limit`, `offset`. For `get` — `{ \"id\": 1363 }` |\n\nThe field set of an `items` element matches the body of [`POST \u002Fv1\u002Fshipment-items`](.\u002Fcreate.md) and [`PATCH \u002Fv1\u002Fshipment-items\u002F:id`](.\u002Fupdate.md). The full list of item fields is in [`GET \u002Fv1\u002Fshipment-items\u002Ffields`](.\u002Ffields.md).\n\nThe `create` body is in the \"Examples\" section. Bodies of the other operations:\n\n- `update` — `{ \"action\": \"update\", \"items\": [{ \"id\": 1363, \"quantity\": 0.75 }] }`\n- `delete` — `{ \"action\": \"delete\", \"ids\": [1363] }`\n- `list` — `{ \"action\": \"list\", \"calls\": [{ \"params\": { \"filter\": { \"orderDeliveryId\": 985 }, \"limit\": 50 } }] }`\n- `get` — `{ \"action\": \"get\", \"calls\": [{ \"params\": { \"id\": 1363 } }] }`\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fshipment-items\u002Fbatch\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"action\": \"create\",\n    \"items\": [\n      { \"orderDeliveryId\": 1215, \"basketId\": 1387, \"quantity\": 0.5 }\n    ]\n  }'\n```\n\n### curl — OAuth application\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fshipment-items\u002Fbatch\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"action\": \"create\",\n    \"items\": [\n      { \"orderDeliveryId\": 1215, \"basketId\": 1387, \"quantity\": 0.5 }\n    ]\n  }'\n```\n\n### JavaScript — personal key\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fshipment-items\u002Fbatch', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({\n    action: 'create',\n    items: [\n      { orderDeliveryId: 1215, basketId: 1387, quantity: 0.5 },\n    ],\n  }),\n})\n\nconst { data } = await res.json()\ndata.results.forEach((item) => {\n  if (item.success) console.log(`#${item.index} → id=${item.id}`)\n  else console.log(`#${item.index} → error: ${item.error} ${item.message}`)\n})\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fshipment-items\u002Fbatch', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({\n    action: 'create',\n    items: [\n      { orderDeliveryId: 1215, basketId: 1387, quantity: 0.5 },\n    ],\n  }),\n})\n\nconst { data } = await res.json()\n```\n\n## Response fields\n\nThe shape of `data` depends on the operation. For `create`, `update` and `delete`:\n\n| Field | Type | Description |\n|------|-----|---------|\n| `success` | boolean | Always `true` if the request passed validation as a whole. The result of each item is in `data.results[i].success` |\n| `data.results` | array | Array of results in the same order as the request's `items` or `ids` |\n| `data.results[].index` | number | Item index, starting from `0` |\n| `data.results[].success` | boolean | Result of this operation |\n| `data.results[].id` | number | ID of the shipment item — created, updated or deleted. Absent in a failed item |\n| `data.results[].error` | string | Error code of a failed item, for example `201250000001` for a repeated `basketId` + `orderDeliveryId` pair |\n| `data.results[].message` | string | Error text of a failed item |\n| `data.summary.total` | number | Total items processed |\n| `data.summary.succeeded` | number | How many succeeded |\n| `data.summary.failed` | number | How many failed |\n\nFor `list` and `get`, the `data` field is an array of results in the order of `calls`, not an object with `results`. Each element carries either `data` or `error`. Here the error code is in the `error` object as `error.code`, while for writes it is a string in `data.results[].error`:\n\n| Field | Type | Description |\n|------|-----|---------|\n| `success` | boolean | Always `true` if the request passed validation as a whole |\n| `data[].data` | array \\| object \\| null | For `list` — an array of items, for `get` — an item object or `null`. Item fields — [Shipment item fields](.\u002Ffields.md). With `select`, an item contains only the listed fields |\n| `data[].total` | number | `list` only — number of items matching the call's filter |\n| `data[].hasMore` | boolean | `list` only — whether there are items beyond `limit` and `offset` |\n| `data[].error.code` | string | Error code of a failed call: `CALL_FAILED` for a non-existent `id`, `INVALID_PARAMS` for a non-integer `id`, a filter validation code for an invalid `filter`, for example `UNKNOWN_FILTER_FIELD` |\n| `data[].error.message` | string | Error text of a failed call |\n\n## Response example\n\n`action: create` — the item is created:\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"results\": [\n      { \"index\": 0, \"success\": true, \"id\": 1363 }\n    ],\n    \"summary\": { \"total\": 1, \"succeeded\": 1, \"failed\": 0 }\n  }\n}\n```\n\n`action: create` — the second item repeated the `basketId` + `orderDeliveryId` pair of the first one and failed, while the top-level `success` stayed `true`:\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"results\": [\n      { \"index\": 0, \"success\": true, \"id\": 1361 },\n      {\n        \"index\": 1,\n        \"success\": false,\n        \"error\": \"201250000001\",\n        \"message\": \"Duplicate entry for key [basketId, orderDeliveryId]\"\n      }\n    ],\n    \"summary\": { \"total\": 2, \"succeeded\": 1, \"failed\": 1 }\n  }\n}\n```\n\n`action: list` — two calls for shipments `975` and `985` with the filter `{ \"orderDeliveryId\": { \"$in\": [975, 985] } }`: the first with `select: [\"id\", \"orderDeliveryId\", \"quantity\"]`, the second with `limit: 1` and `offset: 1`:\n\n```json\n{\n  \"success\": true,\n  \"data\": [\n    {\n      \"data\": [\n        { \"id\": 875, \"orderDeliveryId\": 975, \"quantity\": 1 },\n        { \"id\": 885, \"orderDeliveryId\": 985, \"quantity\": 10 },\n        { \"id\": 887, \"orderDeliveryId\": 985, \"quantity\": 5 }\n      ],\n      \"total\": 3,\n      \"hasMore\": false\n    },\n    {\n      \"data\": [\n        {\n          \"basketId\": 953,\n          \"dateInsert\": \"2025-03-03T22:02:39.000Z\",\n          \"id\": 885,\n          \"orderDeliveryId\": 985,\n          \"quantity\": 10,\n          \"reservedQuantity\": 0,\n          \"xmlId\": \"bx_67c618efc3256\"\n        }\n      ],\n      \"total\": 3,\n      \"hasMore\": true\n    }\n  ]\n}\n```\n\n## Error response example\n\n400 — a `create` item lacks a required field, so the whole batch is rejected:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"BATCH_ITEM_VALIDATION\",\n    \"message\": \"Item at index 0: field 'basketId' is required to create shipmentItem\"\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|------|-----|---------|\n| 400 | `INVALID_BATCH_ACTION` | `action` is not passed or is not one of the allowed operations — the list comes in the error text |\n| 400 | `BATCH_ITEM_VALIDATION` | `items`, `ids` or `calls` is empty or not an array, or an `items` element is not an object |\n| 400 | `BATCH_ITEM_VALIDATION` | A `create` item lacks `orderDeliveryId`, `basketId` or `quantity`, or a read-only field is passed: `id`, `dateInsert`, `reservedQuantity` |\n| 400 | `BATCH_ITEM_VALIDATION` | An `update` item lacks `id`, has no field other than `id`, or a read-only field is passed: `orderDeliveryId`, `basketId` |\n| 400 | `BATCH_ITEM_VALIDATION` | A field value has the wrong type, for example an object in `quantity` — the message names the field and the expected type |\n| 400 | `BATCH_ITEM_VALIDATION` | An item contains an object under `fields`; the message carries the item index and `NESTED_FIELDS_ENVELOPE`. Pass shipment item fields flat at the item's root |\n| 400 | `BATCH_ITEM_VALIDATION` | An ID in `ids` or `items[].id` is not a non-negative integer, for example `\"1.5\"` |\n| 400 | `BATCH_LIMIT_EXCEEDED` | More than 500 elements in `items` or `ids`, or more than 50 calls in `calls` |\n| 403 | `SCOPE_DENIED` | The API key lacks the `sale` scope |\n| 403 | `WRITE_BLOCKED_READONLY_KEY` | `create`, `update` or `delete` with a read-only key — the batch is not executed |\n| 403 | `MANAGEMENT_KEY_NO_ENTITY_ACCESS` | Management key: entity sections are not available to it. A personal key or an OAuth application key is required |\n| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is not passed |\n| 401 | `TOKEN_MISSING` | The API key has no configured tokens |\n| 429 | `RATE_LIMITED` | Rate limit exceeded: 30 requests per minute per portal (a batch costs more than a plain read). All API keys of the portal share one limit. The current limit is returned in the `x-ratelimit-limit` header. Retry after the delay in the `Retry-After` header |\n\nA `400` response means the whole batch is rejected before any write. Errors of individual items come inside a `200` response: for writes — in `data.results[i]` as the `error` and `message` fields, for reads — in `data[i].error`. This is how, for example, an `update` item without `quantity` fails — with the error \"Required fields: quantity\".\n\nFor the full list of common API errors, see [Errors](\u002Fdocs\u002Ferrors).\n\n## Known specifics\n\n**An item of a system shipment is returned as `null` by `get`, and `update` on it fails.** Unlike the single [`GET \u002Fv1\u002Fshipment-items\u002F:id`](.\u002Fget.md), which responds with `404`, a `get` call in the batch returns `{ \"data\": null }` without an error. An `update` element for such an item fails, just like the single [`PATCH`](.\u002Fupdate.md), while the other items of the batch continue to be processed. For an explanation of system shipments, see [Shipment items](\u002Fdocs\u002Fentities\u002Fshipment-items).\n\n## See also\n\n- [Create a shipment item](.\u002Fcreate.md)\n- [Update a shipment item](.\u002Fupdate.md)\n- [Delete a shipment item](.\u002Fdelete.md)\n- [List shipment items](.\u002Flist.md)\n- [Shipment items](\u002Fdocs\u002Fentities\u002Fshipment-items)\n- [Universal batch](\u002Fdocs\u002Fbatch)\n",1795000375982]