## Shipment item fields `GET /v1/shipment-items/fields` Returns the shipment item field schema — a reference for selecting and filtering fields and for the create and update bodies. ## Examples ### curl — personal key ```bash curl "https://vibecode.bitrix24.com/v1/shipment-items/fields" \ -H "X-Api-Key: YOUR_API_KEY" ``` ### curl — OAuth application ```bash curl "https://vibecode.bitrix24.com/v1/shipment-items/fields" \ -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/shipment-items/fields', { headers: { 'X-Api-Key': 'YOUR_API_KEY', }, }) const { data } = await res.json() console.log('Shipment item fields:', Object.keys(data.fields)) ``` ### JavaScript — OAuth application ```javascript const res = await fetch('https://vibecode.bitrix24.com/v1/shipment-items/fields', { headers: { 'X-Api-Key': 'YOUR_APP_KEY', 'Authorization': 'Bearer USER_SESSION_TOKEN', }, }) const { data } = await res.json() ``` ## Response fields | Field | Type | Description | |------|-----|---------| | `success` | boolean | Always `true` on success | | `data.fields` | object | Field schema. The key is the field name, the value is the field description | | `data.fields..type` | string | Value type: `number`, `string`, `datetime` | | `data.fields..readonly` | boolean | `true` means the field is set by the system; passing it on create or update is rejected with `400 READONLY_FIELD` | | `data.fields..required` | boolean | Present only on fields required at creation, always with the value `true` | | `data.fields..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 /v1/shipment-items/:id`](./update.md) is rejected with `400 READONLY_FIELD` | | `data.fields..label` | string | Short field name | | `data.fields..description` | string | Field explanation | | `data.aggregatable` | array | Fields allowed in [shipment item aggregation](./aggregate.md): as the field of a numeric function and as a `groupBy` grouping field | | `data.batch` | array | Operations available in [batch operations on shipment items](./batch.md): `create`, `update`, `delete` | ### Shipment item fields The full set of fields returned by `GET /v1/shipment-items/fields`. The RO column marks read-only fields. | Field | Type | RO | Description | |------|-----|:--:|---------| | `id` | number | yes | Shipment item ID | | `orderDeliveryId` | number | no | Shipment ID. List: [`GET /v1/shipments`](/docs/entities/shipments/list). Required at creation. Set only at creation: on update it is rejected with `400 READONLY_FIELD`, marked `readonlyOnUpdate` in the schema | | `basketId` | number | no | ID of a basket item of the same order. List: [`GET /v1/basket-items`](/docs/entities/basket-items/list). Required at creation. Set only at creation: on update it is rejected with `400 READONLY_FIELD`, marked `readonlyOnUpdate` in the schema | | `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](./update.md): a `PATCH` without `quantity` is rejected with `422 BITRIX_ERROR` | | `reservedQuantity` | number | yes | Reserved quantity | | `xmlId` | string | no | External code of the item | | `dateInsert` | datetime | yes | Creation date in ISO 8601 format, for example `2026-10-07T09:55:27.000Z` | ## Response example ```json { "success": true, "data": { "fields": { "basketId": { "type": "number", "readonly": false, "readonlyOnUpdate": true, "required": true, "label": "Basket item ID", "description": "Basket item of the same order. Lookup: GET /v1/basket-items." }, "dateInsert": { "type": "datetime", "readonly": true, "label": "Creation date", "description": "Creation date." }, "id": { "type": "number", "readonly": true, "label": "Shipment item ID", "description": "Shipment item identifier." }, "orderDeliveryId": { "type": "number", "readonly": false, "readonlyOnUpdate": true, "required": true, "label": "Shipment ID", "description": "Shipment ID. Lookup: GET /v1/shipments." }, "quantity": { "type": "number", "readonly": false, "required": true, "label": "Quantity", "description": "Quantity." }, "reservedQuantity": { "type": "number", "readonly": true, "label": "Reserved", "description": "Reserved." }, "xmlId": { "type": "string", "readonly": false, "label": "External code", "description": "External code." } }, "aggregatable": [ "quantity", "reservedQuantity", "orderDeliveryId", "basketId" ], "batch": [ "create", "update", "delete" ] } } ``` ## Error response example 401 — the API key is not passed: ```json { "success": false, "error": { "code": "MISSING_API_KEY", "message": "API key required. Pass via X-Api-Key header." } } ``` ## Errors | HTTP | Code | Description | |------|-----|---------| | 403 | `SCOPE_DENIED` | The API key has no `sale` scope | | 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 | | 401 | `MISSING_API_KEY` | The `X-Api-Key` header is not passed | | 401 | `INVALID_API_KEY` | The passed API key was not found | | 401 | `TOKEN_MISSING` | The API key has no configured tokens | | 429 | `RATE_LIMITED` | Rate limit exceeded: 300 requests per minute per portal, all API keys of the portal share one limit. The exact value arrives in the `x-ratelimit-limit` header (the cap is divided across replicas). Retry after the delay in the `Retry-After` header | Full list of common API errors — [Errors](/docs/errors). ## See also - [Create a shipment item](./create.md) - [Update a shipment item](./update.md) - [List shipment items](./list.md) - [Shipment item aggregation](./aggregate.md) - [Batch operations on shipment items](./batch.md) - [Shipment items](/docs/entities/shipment-items) - [Shipments](/docs/entities/shipments) - [Basket items](/docs/entities/basket-items) - [Entity reference](/docs/entity-api)