[{"data":1,"prerenderedAt":17},["ShallowReactive",2],{"docs-entities\u002Fshipments":3,"docs-tabs-entities\u002Fshipments":6},{"content":4,"lastmod":5},"# Shipments\n\nOnline store order shipments: delivery service, delivery cost, tracking number, shipping document and the \"shipped\" mark.\n\nBitrix24 API: `sale.shipment.*`\nScope: `sale`\n\n## Operations\n\n- [Create a shipment](.\u002Fshipments\u002Fcreate.md) — `POST \u002Fv1\u002Fshipments`\n- [List shipments](.\u002Fshipments\u002Flist.md) — `GET \u002Fv1\u002Fshipments`\n- [Get a shipment](.\u002Fshipments\u002Fget.md) — `GET \u002Fv1\u002Fshipments\u002F:id`\n- [Update a shipment](.\u002Fshipments\u002Fupdate.md) — `PATCH \u002Fv1\u002Fshipments\u002F:id`\n- [Delete a shipment](.\u002Fshipments\u002Fdelete.md) — `DELETE \u002Fv1\u002Fshipments\u002F:id`\n- [Search shipments](.\u002Fshipments\u002Fsearch.md) — `POST \u002Fv1\u002Fshipments\u002Fsearch`\n- [Shipment fields](.\u002Fshipments\u002Ffields.md) — `GET \u002Fv1\u002Fshipments\u002Ffields`\n- [Aggregate shipments](.\u002Fshipments\u002Faggregate.md) — `POST \u002Fv1\u002Fshipments\u002Faggregate`\n- [Set the \"shipped\" mark](.\u002Fshipments\u002Fship.md) — `POST \u002Fv1\u002Fshipments\u002F:id\u002Fship`\n- [Clear the \"shipped\" mark](.\u002Fshipments\u002Funship.md) — `POST \u002Fv1\u002Fshipments\u002F:id\u002Funship`\n\n## Key fields\n\n| Field | Type | Description |\n|------|-----|---------|\n| `orderId` | number | Order ID. List: [`GET \u002Fv1\u002Forders`](\u002Fdocs\u002Fentities\u002Forders\u002Flist). Set only on creation |\n| `deliveryId` | number | Delivery service ID. List: [`GET \u002Fv1\u002Fdelivery-services`](\u002Fdocs\u002Fentities\u002Fdelivery-services\u002Flist) |\n| `deducted` | boolean | The \"shipped\" mark. Changed only via [`ship`](.\u002Fshipments\u002Fship.md) and [`unship`](.\u002Fshipments\u002Funship.md) |\n| `allowDelivery` | boolean | Delivery allowed. A new shipment without this field is created with `false` |\n| `statusId` | string | Delivery status. List: [`GET \u002Fv1\u002Forder-statuses?filter[type]=D`](\u002Fdocs\u002Fentities\u002Forder-statuses\u002Flist) |\n| `responsibleId` | number | Responsible employee. List: [`GET \u002Fv1\u002Fusers`](\u002Fdocs\u002Fentities\u002Fusers\u002Flist) |\n| `priceDelivery` | number | Delivery cost |\n| `shipmentItems` | array | Shipment items. Changed via [shipment items](\u002Fdocs\u002Fentities\u002Fshipment-items) |\n\nFull field list — [`GET \u002Fv1\u002Fshipments\u002Ffields`](.\u002Fshipments\u002Ffields.md).\n\n## What to know before you start\n\n1. **A shipment always belongs to an order.** Creation requires `orderId` and `deliveryId`; a shipment cannot be moved to another order. The shipment number `accountNumber` is built from the order number and the shipment's sequence number joined by `\u002F`, for example `1027\u002F2`.\n2. **A new shipment may be created without items.** Shipment contents are set separately, via [shipment items](\u002Fdocs\u002Fentities\u002Fshipment-items). After creation, check `shipmentItems` in [`GET \u002Fv1\u002Fshipments\u002F:id`](.\u002Fshipments\u002Fget.md).\n3. **The \"shipped\" mark is set by a separate action.** The `deducted` field in a create or update body is rejected with `400 READONLY_FIELD`. A new shipment is created without the mark; set it via [`POST \u002Fv1\u002Fshipments\u002F:id\u002Fship`](.\u002Fshipments\u002Fship.md). With inventory management enabled, the mark may write off stock from the warehouse.\n4. **Updates keep fields you do not send.** [`PATCH \u002Fv1\u002Fshipments\u002F:id`](.\u002Fshipments\u002Fupdate.md) reads the shipment before writing, so send only the fields you change. The update is rejected if the shipment cannot be saved without loss: an empty responsible employee, an empty shipment company while the order has a different company, or a manual delivery cost (`customPriceDelivery: true`). Change such a shipment in the Bitrix24 interface.\n5. **System shipments are not returned.** List and search return only shipments with `system: false`. The `filter[system]=true` filter returns an empty list.\n\n## Typical scenario\n\n1. Find the order: [`GET \u002Fv1\u002Forders`](\u002Fdocs\u002Fentities\u002Forders\u002Flist).\n2. Pick a delivery service: [`GET \u002Fv1\u002Fdelivery-services`](\u002Fdocs\u002Fentities\u002Fdelivery-services\u002Flist).\n3. Create the shipment: [`POST \u002Fv1\u002Fshipments`](.\u002Fshipments\u002Fcreate.md) with `orderId` and `deliveryId`.\n4. Fill the shipment with items: [shipment items](\u002Fdocs\u002Fentities\u002Fshipment-items).\n5. Record the tracking number and document number: [`PATCH \u002Fv1\u002Fshipments\u002F:id`](.\u002Fshipments\u002Fupdate.md).\n6. When the goods are handed over for delivery, set the mark: [`POST \u002Fv1\u002Fshipments\u002F:id\u002Fship`](.\u002Fshipments\u002Fship.md).\n\n## Limits\n\n| Limit | Value |\n|-------|----------|\n| Records per list request | up to 5000 (`limit`), 50 by default |\n| Aggregation | up to 5 `aggregate` expressions per request, functions `count`, `sum`, `avg`, `min`, `max` |\n| Batch calls | not supported: [`POST \u002Fv1\u002Fbatch`](\u002Fdocs\u002Fbatch) returns `ACTION_NOT_SUPPORTED` for `shipments`; call the section's endpoints one at a time |\n| Rate limit | shared across the Vibecode API — see [Limits and optimization](\u002Fdocs\u002Foptimization) |\n\n## See also\n\n- [Shipment items](\u002Fdocs\u002Fentities\u002Fshipment-items)\n- [Orders](\u002Fdocs\u002Fentities\u002Forders)\n- [Delivery services](\u002Fdocs\u002Fentities\u002Fdelivery-services)\n- [Order statuses](\u002Fdocs\u002Fentities\u002Forder-statuses)\n- [CRM deliveries](\u002Fdocs\u002Fentities\u002Fcrm-deliveries)\n- [Entity reference](\u002Fdocs\u002Fentity-api)\n","2026-10-07",{"shipments\u002Fcreate.md":7,"shipments\u002Flist.md":8,"shipments\u002Fget.md":9,"shipments\u002Fupdate.md":10,"shipments\u002Fdelete.md":11,"shipments\u002Fsearch.md":12,"shipments\u002Ffields.md":13,"shipments\u002Faggregate.md":14,"shipments\u002Fship.md":15,"shipments\u002Funship.md":16},"## Create a shipment\n\n`POST \u002Fv1\u002Fshipments`\n\nCreates a shipment in an existing online store order and assigns a delivery service to it.\n\nFields are passed flat at the JSON root, without a `fields` wrapper.\n\n## Request fields (body)\n\n| Field | Type | Required | Description |\n|------|-----|:-----:|---------|\n| `orderId` | number | yes | ID of the order in which the shipment is created. List: [`GET \u002Fv1\u002Forders`](\u002Fdocs\u002Fentities\u002Forders\u002Flist). Cannot be changed after creation |\n| `deliveryId` | number | yes | Delivery service ID. List: [`GET \u002Fv1\u002Fdelivery-services`](\u002Fdocs\u002Fentities\u002Fdelivery-services\u002Flist) |\n| `allowDelivery` | boolean | no | Whether delivery is allowed. If omitted, the shipment is created with `false` |\n| `statusId` | string | no | Delivery status. List: [`GET \u002Fv1\u002Forder-statuses?filter[type]=D`](\u002Fdocs\u002Fentities\u002Forder-statuses\u002Flist). If omitted, the shipment gets the Bitrix24 account's initial delivery status, `DN` in the example below |\n| `trackingNumber` | string | no | Tracking number |\n| `deliveryDocNum` | string | no | Shipment document number |\n| `deliveryDocDate` | datetime | no | Shipment document date |\n| `priceDelivery` | number | no | Delivery price. If omitted, the delivery service price is used |\n| `basePriceDelivery` | number | no | Base delivery price |\n| `responsibleId` | number | no | ID of the responsible employee. List: [`GET \u002Fv1\u002Fusers`](\u002Fdocs\u002Fentities\u002Fusers\u002Flist). If omitted, the responsible person is assigned automatically |\n| `companyId` | number | no | CRM company ID. List: [`GET \u002Fv1\u002Fcompanies`](\u002Fdocs\u002Fentities\u002Fcompanies\u002Flist). The company's existence is not checked |\n| `comments` | string | no | Shipment comment |\n| `xmlId` | string | no | External code. If omitted, it is generated automatically |\n\nFull field list — [`GET \u002Fv1\u002Fshipments\u002Ffields`](.\u002Ffields.md).\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fshipments\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"orderId\": 1027,\n    \"deliveryId\": 1,\n    \"trackingNumber\": \"VIBE-DOC-1\",\n    \"comments\": \"Test shipment for documentation\"\n  }'\n```\n\n### curl — OAuth application\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fshipments\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"orderId\": 1027,\n    \"deliveryId\": 1,\n    \"trackingNumber\": \"VIBE-DOC-1\",\n    \"comments\": \"Test shipment for documentation\"\n  }'\n```\n\n### JavaScript — personal key\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fshipments', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({\n    orderId: 1027,\n    deliveryId: 1,\n    trackingNumber: 'VIBE-DOC-1',\n    comments: 'Test shipment for documentation',\n  }),\n})\n\nconst { success, data } = await res.json()\nconsole.log('Shipment ID:', data.id)\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fshipments', {\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    orderId: 1027,\n    deliveryId: 1,\n    trackingNumber: 'VIBE-DOC-1',\n    comments: 'Test shipment for documentation',\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 with all fields — [Shipment fields](.\u002Ffields.md) |\n| `data.id` | number | ID of the created shipment |\n| `data.accountNumber` | string | Shipment number: the order number and the shipment's sequence number separated by `\u002F` |\n| `data.deducted` | boolean | The \"shipped\" mark. Always `false` for a new shipment |\n| `data.deliveryName` | string | Name of the delivery service from `deliveryId` |\n| `data.shipmentItems` | array | Shipment items. An empty array if no items have been added yet |\n| `data.system` | boolean | System shipment. Always `false` for a shipment created via the API |\n\n## Response example\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"accountNumber\": \"1027\u002F2\",\n    \"allowDelivery\": false,\n    \"basePriceDelivery\": 500,\n    \"canceled\": false,\n    \"comments\": \"Test shipment for documentation\",\n    \"companyId\": null,\n    \"currency\": \"USD\",\n    \"customPriceDelivery\": false,\n    \"dateAllowDelivery\": null,\n    \"dateCanceled\": null,\n    \"dateDeducted\": null,\n    \"dateInsert\": \"2026-10-06T11:30:44.000Z\",\n    \"dateMarked\": null,\n    \"dateResponsibleId\": \"2026-10-06T11:30:44.000Z\",\n    \"deducted\": false,\n    \"deliveryDocDate\": null,\n    \"deliveryDocNum\": null,\n    \"deliveryId\": 1,\n    \"deliveryName\": \"Courier delivery\",\n    \"deliveryXmlId\": null,\n    \"discountPrice\": 0,\n    \"empAllowDeliveryId\": null,\n    \"empCanceledId\": null,\n    \"empDeductedId\": null,\n    \"empMarkedId\": null,\n    \"empResponsibleId\": 1317,\n    \"externalDelivery\": false,\n    \"id\": 1205,\n    \"id1c\": null,\n    \"marked\": false,\n    \"orderId\": 1027,\n    \"priceDelivery\": 500,\n    \"reasonMarked\": null,\n    \"reasonUndoDeducted\": null,\n    \"responsibleId\": 1295,\n    \"shipmentItems\": [],\n    \"statusId\": \"DN\",\n    \"statusXmlId\": null,\n    \"system\": false,\n    \"trackingDescription\": null,\n    \"trackingLastCheck\": null,\n    \"trackingNumber\": \"VIBE-DOC-1\",\n    \"trackingStatus\": null,\n    \"updated1c\": false,\n    \"version1c\": null,\n    \"xmlId\": \"bx_6ac4cdd46e442\"\n  }\n}\n```\n\n## Error response example\n\n422 — no order with this `orderId` exists:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"BITRIX_ERROR\",\n    \"message\": \"Unable to load the order\",\n    \"b24Code\": \"0\"\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|------|-----|---------|\n| 400 | `MISSING_REQUIRED_FIELDS` | The required field `orderId` or `deliveryId` is missing or empty. The field name is in `message` |\n| 400 | `READONLY_FIELD` | The body contains `deducted`. The response contains a `hint` with the [`ship`](.\u002Fship.md) and [`unship`](.\u002Funship.md) endpoints |\n| 400 | `READONLY_FIELD` | The body contains another read-only field, such as `customPriceDelivery` or `accountNumber`. The field name is in `message` |\n| 400 | `INVALID_PARAMS` | A field value does not match its type, such as a word in the numeric `deliveryId` or an object in the text `comments`. The field name is in `message` |\n| 422 | `BITRIX_ERROR` | Bitrix24 rejected the creation. For example, no order with this `orderId` exists — `Unable to load the order` |\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| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |\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- [Shipments](\u002Fdocs\u002Fentities\u002Fshipments)\n- [Get a shipment](.\u002Fget.md)\n- [Update a shipment](.\u002Fupdate.md)\n- [Set the \"shipped\" mark](.\u002Fship.md)\n- [Delete a shipment](.\u002Fdelete.md)\n- [Shipment items](\u002Fdocs\u002Fentities\u002Fshipment-items)\n- [Orders](\u002Fdocs\u002Fentities\u002Forders)\n- [Delivery services](\u002Fdocs\u002Fentities\u002Fdelivery-services)\n","## List shipments\n\n`GET \u002Fv1\u002Fshipments`\n\nReturns a list of online store order shipments with support for 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 reduced to 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 field selection: `?select=id,orderId,deducted,trackingNumber`. 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 | — | Sorting via the short syntax: `?sort=-id`, where a leading minus means descending order |\n| `order` (query) | object | — | Sorting: `?order[id]=desc` |\n| `filter` (query) | object | — | Filtering by the fields from `GET \u002Fv1\u002Fshipments\u002Ffields`.\u003Cbr>[Filtering syntax](\u002Fdocs\u002Ffiltering). Example: `?filter[orderId]=1027` |\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 follow.\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl -g \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fshipments?select=id,orderId,deducted,trackingNumber&filter[orderId]=1027\" \\\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\u002Fshipments?select=id,orderId,deducted,trackingNumber&filter[orderId]=1027\" \\\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\u002Fshipments?select=id,orderId,deducted,trackingNumber&filter[orderId]=1027', {\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n  },\n})\n\nconst { success, data, meta } = await res.json()\nconsole.log(`Shipments in the order: ${data.length}`)\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fshipments?select=id,orderId,deducted,trackingNumber&filter[orderId]=1027', {\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 shipments. All fields — [Shipment fields](\u002Fdocs\u002Fentities\u002Fshipments\u002Ffields) |\n| `meta.total` | number | Total number of records matching the filter. May be absent — see the `withTotal` parameter |\n| `meta.hasMore` | boolean | Whether there are more records 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\nA request with `select` returns only the listed fields:\n\n```json\n{\n  \"success\": true,\n  \"data\": [\n    {\n      \"id\": 1205,\n      \"orderId\": 1027,\n      \"deducted\": false,\n      \"trackingNumber\": \"VIBE-DOC-1\"\n    }\n  ],\n  \"meta\": {\n    \"total\": 1,\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 'shipments'. Available: accountNumber, allowDelivery, basePriceDelivery, canceled, comments, companyId, currency, customPriceDelivery, dateAllowDelivery, dateCanceled, dateDeducted, dateInsert, dateMarked, dateResponsibleId, deducted, deliveryDocDate, deliveryDocNum, deliveryId, deliveryName, deliveryXmlId, discountPrice, empAllowDeliveryId, empCanceledId, empDeductedId, empMarkedId, empResponsibleId, externalDelivery, id, id1c, marked, orderId, priceDelivery, reasonMarked, reasonUndoDeducted, responsibleId, statusId, statusXmlId, system, trackingDescription, trackingLastCheck, trackingNumber, trackingStatus, updated1c, version1c, xmlId, shipmentItems\"\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\u002Fshipments\u002Ffields`](\u002Fdocs\u002Fentities\u002Fshipments\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, or the logical condition `$or`, which cannot be expressed in a query string |\n| 400 | `INVALID_FILTER` | The `filter` parameter is neither an object nor a JSON string, or one request mixes both filter notations |\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 or cannot be sorted on |\n| 400 | `INVALID_SORT_DIRECTION` | The direction in `order` is not one of `asc`, `desc`, `ASC`, `DESC`, `1`, `-1` |\n| 403 | `SCOPE_DENIED` | The API key does not have 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` | 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 list has no shipment items.** The `data` items do not contain the `shipmentItems` field. The shipment contents are returned by [`GET \u002Fv1\u002Fshipments\u002F:id`](\u002Fdocs\u002Fentities\u002Fshipments\u002Fget).\n\n**When to use `search` instead of `list`:** [`POST \u002Fv1\u002Fshipments\u002Fsearch`](\u002Fdocs\u002Fentities\u002Fshipments\u002Fsearch) passes parameters in the request body rather than the query string, and splits the selection into time windows when filtering by a date range wider than 14 days.\n\n## See also\n\n- [Search shipments](\u002Fdocs\u002Fentities\u002Fshipments\u002Fsearch)\n- [Get a shipment](\u002Fdocs\u002Fentities\u002Fshipments\u002Fget)\n- [Create a shipment](\u002Fdocs\u002Fentities\u002Fshipments\u002Fcreate)\n- [Shipment fields](\u002Fdocs\u002Fentities\u002Fshipments\u002Ffields)\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\n\n`GET \u002Fv1\u002Fshipments\u002F:id`\n\nReturns a single online store order shipment by its ID.\n\n## Parameters\n\n| Parameter | Type | Required | Description |\n|----------|-----|:-----:|---------|\n| `id` (path) | number | yes | Shipment ID. List: [`GET \u002Fv1\u002Fshipments`](\u002Fdocs\u002Fentities\u002Fshipments\u002Flist) |\n| `select` (query) | string | no | Comma-separated field selection: `?select=id,orderId,trackingNumber`. Only the listed fields are returned in `data`. Field list: [`GET \u002Fv1\u002Fshipments\u002Ffields`](\u002Fdocs\u002Fentities\u002Fshipments\u002Ffields) |\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fshipments\u002F1205\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\"\n```\n\n### curl — OAuth application\n\n```bash\ncurl \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fshipments\u002F1205\" \\\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\u002Fshipments\u002F1205', {\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n  },\n})\n\nconst { success, data } = await res.json()\nconsole.log('Shipment:', data.accountNumber, '— items:', data.shipmentItems.length)\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fshipments\u002F1205', {\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 with all fields — see [Shipment fields](\u002Fdocs\u002Fentities\u002Fshipments\u002Ffields) |\n| `data.shipmentItems` | array | Shipment items. An empty array if there are no items. To change the items, use [shipment items](\u002Fdocs\u002Fentities\u002Fshipment-items) |\n\n## Response example\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"accountNumber\": \"1027\u002F2\",\n    \"allowDelivery\": false,\n    \"basePriceDelivery\": 500,\n    \"canceled\": false,\n    \"comments\": \"Test shipment for documentation\",\n    \"companyId\": null,\n    \"currency\": \"USD\",\n    \"customPriceDelivery\": false,\n    \"dateAllowDelivery\": null,\n    \"dateCanceled\": null,\n    \"dateDeducted\": null,\n    \"dateInsert\": \"2026-10-06T11:30:44.000Z\",\n    \"dateMarked\": null,\n    \"dateResponsibleId\": \"2026-10-06T11:30:44.000Z\",\n    \"deducted\": false,\n    \"deliveryDocDate\": null,\n    \"deliveryDocNum\": null,\n    \"deliveryId\": 1,\n    \"deliveryName\": \"Courier delivery\",\n    \"deliveryXmlId\": null,\n    \"discountPrice\": 0,\n    \"empAllowDeliveryId\": null,\n    \"empCanceledId\": null,\n    \"empDeductedId\": null,\n    \"empMarkedId\": null,\n    \"empResponsibleId\": 1317,\n    \"externalDelivery\": false,\n    \"id\": 1205,\n    \"id1c\": null,\n    \"marked\": false,\n    \"orderId\": 1027,\n    \"priceDelivery\": 500,\n    \"reasonMarked\": null,\n    \"reasonUndoDeducted\": null,\n    \"responsibleId\": 1295,\n    \"shipmentItems\": [],\n    \"statusId\": \"DN\",\n    \"statusXmlId\": null,\n    \"system\": false,\n    \"trackingDescription\": null,\n    \"trackingLastCheck\": null,\n    \"trackingNumber\": \"VIBE-DOC-1\",\n    \"trackingStatus\": null,\n    \"updated1c\": false,\n    \"version1c\": null,\n    \"xmlId\": \"bx_6ac4cdd46e442\"\n  }\n}\n```\n\n## Error response example\n\n404 — shipment not found:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"ENTITY_NOT_FOUND\",\n    \"message\": \"shipment 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 with this `id`. Error text — `shipment is not exists` |\n| 404 | `ENTITY_NOT_FOUND` | The request succeeded, but the response contains no shipment. Error text — `shipment \u003Cid> not found` |\n| 403 | `SCOPE_DENIED` | The API key does not have 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\nFull list of common API errors — [Errors](\u002Fdocs\u002Ferrors).\n\n## See also\n\n- [List shipments](\u002Fdocs\u002Fentities\u002Fshipments\u002Flist)\n- [Search shipments](\u002Fdocs\u002Fentities\u002Fshipments\u002Fsearch)\n- [Update a shipment](\u002Fdocs\u002Fentities\u002Fshipments\u002Fupdate)\n- [Shipment fields](\u002Fdocs\u002Fentities\u002Fshipments\u002Ffields)\n- [Shipment items](\u002Fdocs\u002Fentities\u002Fshipment-items)\n- [Shipments](\u002Fdocs\u002Fentities\u002Fshipments)\n","## Update a shipment\n\n`PATCH \u002Fv1\u002Fshipments\u002F:id`\n\nUpdates an existing shipment of an online store order. Omitted fields are preserved.\n\nFields are passed flat at the JSON root, without a `fields` wrapper. How omitted fields are preserved — [Shipments](\u002Fdocs\u002Fentities\u002Fshipments).\n\n## Parameters\n\n| Parameter | Type | Required | Description |\n|----------|-----|:-----:|---------|\n| `id` (path) | number | yes | Shipment ID. List: [`GET \u002Fv1\u002Fshipments`](.\u002Flist.md) |\n\n## Request fields (body)\n\n| Field | Type | Description |\n|------|-----|---------|\n| `trackingNumber` | string | Tracking number |\n| `deliveryDocNum` | string | Shipment document number |\n| `deliveryDocDate` | datetime | Shipment document date |\n| `allowDelivery` | boolean | Delivery is allowed |\n| `statusId` | string | Delivery status. List: [`GET \u002Fv1\u002Forder-statuses?filter[type]=D`](\u002Fdocs\u002Fentities\u002Forder-statuses\u002Flist) |\n| `deliveryId` | number | Delivery service ID. List: [`GET \u002Fv1\u002Fdelivery-services`](\u002Fdocs\u002Fentities\u002Fdelivery-services\u002Flist) |\n| `priceDelivery` | number | Delivery price |\n| `basePriceDelivery` | number | Base delivery price |\n| `responsibleId` | number | ID of the responsible employee. List: [`GET \u002Fv1\u002Fusers`](\u002Fdocs\u002Fentities\u002Fusers\u002Flist). An empty value, `null` or `0`, is not accepted |\n| `companyId` | number | CRM company ID. List: [`GET \u002Fv1\u002Fcompanies`](\u002Fdocs\u002Fentities\u002Fcompanies\u002Flist). The company's existence is not checked. An empty value is accepted only if the order has no company either — the `companyId` field in [`GET \u002Fv1\u002Forders\u002F:id`](\u002Fdocs\u002Fentities\u002Forders\u002Fget) |\n| `comments` | string | Shipment comment |\n| `xmlId` | string | External code |\n| `orderId` | number | RO. Set only on [creation](.\u002Fcreate.md) |\n| `deducted` | boolean | RO. Changed via [`ship`](.\u002Fship.md) and [`unship`](.\u002Funship.md) |\n| `customPriceDelivery` | boolean | RO. Manual delivery price flag |\n\nFull field list — [`GET \u002Fv1\u002Fshipments\u002Ffields`](.\u002Ffields.md).\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl -X PATCH \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fshipments\u002F1205\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"trackingNumber\": \"VIBE-DOC-2\",\n    \"deliveryDocNum\": \"TN-1205\",\n    \"allowDelivery\": true\n  }'\n```\n\n### curl — OAuth application\n\n```bash\ncurl -X PATCH \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fshipments\u002F1205\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"trackingNumber\": \"VIBE-DOC-2\",\n    \"deliveryDocNum\": \"TN-1205\",\n    \"allowDelivery\": true\n  }'\n```\n\n### JavaScript — personal key\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fshipments\u002F1205', {\n  method: 'PATCH',\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({\n    trackingNumber: 'VIBE-DOC-2',\n    deliveryDocNum: 'TN-1205',\n    allowDelivery: true,\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\u002Fshipments\u002F1205', {\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    trackingNumber: 'VIBE-DOC-2',\n    deliveryDocNum: 'TN-1205',\n    allowDelivery: true,\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 with all fields, including omitted ones. All fields — [Shipment fields](.\u002Ffields.md) |\n\n## Response example\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"accountNumber\": \"1027\u002F2\",\n    \"allowDelivery\": true,\n    \"basePriceDelivery\": 500,\n    \"canceled\": false,\n    \"comments\": \"Test shipment for documentation\",\n    \"companyId\": null,\n    \"currency\": \"USD\",\n    \"customPriceDelivery\": false,\n    \"dateAllowDelivery\": \"2026-10-06T11:31:17.000Z\",\n    \"dateCanceled\": null,\n    \"dateDeducted\": null,\n    \"dateInsert\": \"2026-10-06T11:30:44.000Z\",\n    \"dateMarked\": null,\n    \"dateResponsibleId\": \"2026-10-06T11:30:44.000Z\",\n    \"deducted\": false,\n    \"deliveryDocDate\": null,\n    \"deliveryDocNum\": \"TN-1205\",\n    \"deliveryId\": 1,\n    \"deliveryName\": \"Courier delivery\",\n    \"deliveryXmlId\": null,\n    \"discountPrice\": 0,\n    \"empAllowDeliveryId\": 1317,\n    \"empCanceledId\": null,\n    \"empDeductedId\": null,\n    \"empMarkedId\": null,\n    \"empResponsibleId\": 1317,\n    \"externalDelivery\": false,\n    \"id\": 1205,\n    \"id1c\": null,\n    \"marked\": false,\n    \"orderId\": 1027,\n    \"priceDelivery\": 500,\n    \"reasonMarked\": null,\n    \"reasonUndoDeducted\": null,\n    \"responsibleId\": 1295,\n    \"shipmentItems\": [],\n    \"statusId\": \"DN\",\n    \"statusXmlId\": null,\n    \"system\": false,\n    \"trackingDescription\": null,\n    \"trackingLastCheck\": null,\n    \"trackingNumber\": \"VIBE-DOC-2\",\n    \"trackingStatus\": null,\n    \"updated1c\": false,\n    \"version1c\": null,\n    \"xmlId\": \"bx_6ac4cdd46e442\"\n  }\n}\n```\n\n## Error response example\n\n400 — an empty `responsibleId` was passed:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"INVALID_PARAMS\",\n    \"message\": \"Bitrix24 cannot preserve an empty shipment responsibleId and its assignment metadata. Set an explicit nonzero responsibleId or update the shipment in Bitrix24.\"\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|------|-----|---------|\n| 400 | `READONLY_FIELD` | The body contains `deducted`. The response contains a `hint` with the [`ship`](.\u002Fship.md) and [`unship`](.\u002Funship.md) endpoints |\n| 400 | `READONLY_FIELD` | The body contains another read-only field: `customPriceDelivery`, `orderId`, `accountNumber` and others. The field name is in `message` |\n| 400 | `EMPTY_UPDATE_BODY` | The request body is empty |\n| 400 | `INVALID_PARAMS` | The body contains no known shipment field — `At least one writable shipment field is required.` |\n| 400 | `INVALID_PARAMS` | The same field is passed twice under different names, such as `trackingNumber` and `TRACKING_NUMBER` — `Duplicate field alias` |\n| 400 | `INVALID_PARAMS` | The responsible person would be empty after the write: `responsibleId` is passed as `null` or `0`, or it is omitted and the stored shipment has no responsible person. Pass a nonzero `responsibleId` |\n| 400 | `INVALID_PARAMS` | The shipment company would be empty after the write, while the order has a different company. Pass a nonzero `companyId` |\n| 400 | `INVALID_PARAMS` | The stored shipment has a manual delivery price (`customPriceDelivery` is `true`). Change such a shipment in the Bitrix24 interface |\n| 400 | `INVALID_PARAMS` | A field value does not match its type, such as a word in the numeric `priceDelivery` or an object in the text `comments`. 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 with this `id` exists |\n| 422 | `BITRIX_NO_EFFECT` | Bitrix24 did not return the shipment fields or the order needed to preserve the omitted fields. No write was performed |\n| 422 | `BITRIX_ERROR` | Bitrix24 rejected the write or the read of the shipment's order. The reason 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| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |\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**Allowing delivery records the date and the employee.** After `allowDelivery: true`, the response contains the date delivery was allowed, `dateAllowDelivery`, and the ID of the employee who allowed it, `empAllowDeliveryId`.\n\n**Field names are also accepted in upper case.** `TRACKING_NUMBER` is saved the same way as `trackingNumber`.\n\n## See also\n\n- [Shipments](\u002Fdocs\u002Fentities\u002Fshipments)\n- [Get a shipment](.\u002Fget.md)\n- [Create a shipment](.\u002Fcreate.md)\n- [Set the \"shipped\" mark](.\u002Fship.md)\n- [Remove the \"shipped\" mark](.\u002Funship.md)\n- [Shipment fields](.\u002Ffields.md)\n- [Shipment items](\u002Fdocs\u002Fentities\u002Fshipment-items)\n","## Delete a shipment\n\n`DELETE \u002Fv1\u002Fshipments\u002F:id`\n\nDeletes an online store order shipment by its ID. A deleted shipment cannot be restored via the API; create a new one if needed.\n\n## Parameters\n\n| Parameter | Type | Required | Description |\n|----------|-----|:-----:|---------|\n| `id` (path) | number | yes | Shipment ID, a non-negative integer. List: [`GET \u002Fv1\u002Fshipments`](.\u002Flist.md) |\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl -X DELETE \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fshipments\u002F1205\" \\\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\u002Fshipments\u002F1205\" \\\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\u002Fshipments\u002F1205', {\n  method: 'DELETE',\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n  },\n})\n\nif (res.status === 204) {\n  console.log('Shipment deleted')\n}\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fshipments\u002F1205', {\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 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 the content.\n\n## Response example\n\n```http\nHTTP\u002F1.1 204 No Content\n```\n\n## Error response example\n\n422 — the shipment has the \"shipped\" mark:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"BITRIX_ERROR\",\n    \"message\": \"The shipment has already been shipped. Cancel the shipment\",\n    \"b24Code\": \"SALE_SHIPMENT_EXIST_SHIPPED\"\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|------|-----|---------|\n| 400 | `INVALID_PARAMS` | The `id` in the path is not a non-negative integer. Error message: `id must be a non-negative integer` |\n| 404 | `ENTITY_NOT_FOUND` | No shipment with this `id` exists, or it has already been deleted. Error message: `shipment is not exists` |\n| 422 | `BITRIX_ERROR` | The shipment has the \"shipped\" mark, and `b24Code` is `SALE_SHIPMENT_EXIST_SHIPPED`. Clear the mark via [`POST \u002Fv1\u002Fshipments\u002F:id\u002Funship`](.\u002Funship.md) |\n| 422 | `BITRIX_ERROR` | Bitrix24 rejected the deletion 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 is in read-only mode |\n| 403 | `SCOPE_DENIED` | The API key does not have 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\nFull list of common API errors: [Errors](\u002Fdocs\u002Ferrors).\n\n## See also\n\n- [Clear the \"shipped\" mark](.\u002Funship.md)\n- [Get a shipment](.\u002Fget.md)\n- [Create a shipment](.\u002Fcreate.md)\n- [Shipment items](\u002Fdocs\u002Fentities\u002Fshipment-items)\n- [Shipments](\u002Fdocs\u002Fentities\u002Fshipments)\n","## Search shipments\n\n`POST \u002Fv1\u002Fshipments\u002Fsearch`\n\nSearches online store order shipments 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 list is enough.\n\n## Request fields (body)\n\n| Field | Type | Default | Description |\n|------|-----|-----------|---------|\n| `filter` | object | — | Filtering by the fields from `GET \u002Fv1\u002Fshipments\u002Ffields`.\u003Cbr>[Filtering syntax](\u002Fdocs\u002Ffiltering). Example: `{ \"orderId\": 1027, \"deducted\": false }` |\n| `select` | string[] | — | Field selection: `[\"id\", \"orderId\", \"deliveryName\", \"priceDelivery\", \"trackingNumber\"]`. 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 | — | Sorting via the short syntax: `\"-id\"`, the minus means descending |\n| `order` | object | — | Sorting as an object: `{ \"id\": \"desc\" }`. If `sort` is also passed, `sort` takes effect |\n| `limit` | number | `50` | Number of records, up to 5000 |\n| `offset` | number | `0` | Skip N records. Rejected when combined with a date range filter wider than 14 days — see `UNSTABLE_OFFSET_PAGINATION` in the \"Errors\" section |\n| `autoWindow` | boolean | `true` | Split the selection into weekly windows when filtering by a date range wider than 14 days. `false` disables splitting |\n| `withTotal` | boolean | — | 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\u002Fshipments\u002Fsearch\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"filter\": { \"orderId\": 1027, \"deducted\": false },\n    \"select\": [\"id\", \"orderId\", \"deliveryName\", \"priceDelivery\", \"trackingNumber\"],\n    \"sort\": \"-id\",\n    \"limit\": 10\n  }'\n```\n\n### curl — OAuth application\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fshipments\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\": { \"orderId\": 1027, \"deducted\": false },\n    \"select\": [\"id\", \"orderId\", \"deliveryName\", \"priceDelivery\", \"trackingNumber\"],\n    \"sort\": \"-id\",\n    \"limit\": 10\n  }'\n```\n\n### JavaScript — personal key\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fshipments\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: { orderId: 1027, deducted: false },\n    select: ['id', 'orderId', 'deliveryName', 'priceDelivery', 'trackingNumber'],\n    sort: '-id',\n    limit: 10,\n  }),\n})\n\nconst { success, data, meta } = await res.json()\nconsole.log('Not marked as shipped:', data.length)\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fshipments\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: { orderId: 1027, deducted: false },\n    select: ['id', 'orderId', 'deliveryName', 'priceDelivery', 'trackingNumber'],\n    sort: '-id',\n    limit: 10,\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 shipments. All fields — [Shipment fields](\u002Fdocs\u002Fentities\u002Fshipments\u002Ffields) |\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. Returned when `autoWindowed` is `true` |\n| `meta.windowErrors` | number | How many windows ended with an error. Returned if some windows failed |\n| `meta.windowErrorSample` | object | Error code and message of the first failed window. Returned with `windowErrors` |\n| `meta.batchWaves` | number | Number of waves of parallel requests. Returned when `autoWindowed` is `true` |\n| `meta.warnings` | array | Warnings about request parameters: `code`, `message`, `field`. Returned only when there are warnings |\n| `meta.pageErrorSample` | object | Code and message of the error that stopped automatic pagination early. Returned 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\": 1205,\n      \"orderId\": 1027,\n      \"deliveryName\": \"Courier delivery\",\n      \"priceDelivery\": 500,\n      \"trackingNumber\": \"VIBE-DOC-1\"\n    }\n  ],\n  \"meta\": {\n    \"total\": 1,\n    \"hasMore\": false,\n    \"durationMs\": 278\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 'unknownField' for entity 'shipments'. Available: accountNumber, allowDelivery, basePriceDelivery, canceled, comments, companyId, currency, customPriceDelivery, dateAllowDelivery, dateCanceled, dateDeducted, dateInsert, dateMarked, dateResponsibleId, deducted, deliveryDocDate, deliveryDocNum, deliveryId, deliveryName, deliveryXmlId, discountPrice, empAllowDeliveryId, empCanceledId, empDeductedId, empMarkedId, empResponsibleId, externalDelivery, id, id1c, marked, orderId, priceDelivery, reasonMarked, reasonUndoDeducted, responsibleId, statusId, statusXmlId, system, trackingDescription, trackingLastCheck, trackingNumber, trackingStatus, updated1c, version1c, xmlId, shipmentItems\"\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\u002Fshipments\u002Ffields`](\u002Fdocs\u002Fentities\u002Fshipments\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 `$nin` on the same field. Pass only one of them |\n| 400 | `UNKNOWN_SORT_FIELD` | Sorting by a field that is not in the schema or cannot be sorted on |\n| 400 | `INVALID_SORT_TYPE` | `sort` or `order` is passed as a value of an unsuitable type, for example a number |\n| 400 | `INVALID_SORT_DIRECTION` | The direction in `order` 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| 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` | 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.** A filter by a date field (`dateInsert`, `dateDeducted`, `dateAllowDelivery`, and others) with a range wider than 14 days is split into weekly windows that run in parallel waves. This lets the selection get past the cap of 5000 records per call.\n\n**A partial window failure does not abort the request.** If some of the windows failed, the response arrives 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 shipments](\u002Fdocs\u002Fentities\u002Fshipments\u002Flist)\n- [Get a shipment](\u002Fdocs\u002Fentities\u002Fshipments\u002Fget)\n- [Shipment aggregation](\u002Fdocs\u002Fentities\u002Fshipments\u002Faggregate)\n- [Shipment fields](\u002Fdocs\u002Fentities\u002Fshipments\u002Ffields)\n- [Shipments](\u002Fdocs\u002Fentities\u002Fshipments)\n- [Filtering syntax](\u002Fdocs\u002Ffiltering)\n- [Entity reference](\u002Fdocs\u002Fentity-api)\n- [Limits and optimization](\u002Fdocs\u002Foptimization)\n","## Shipment fields\n\n`GET \u002Fv1\u002Fshipments\u002Ffields`\n\nReturns the shipment 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\u002Fshipments\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\u002Fshipments\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\u002Fshipments\u002Ffields', {\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n  },\n})\n\nconst { data } = await res.json()\nconsole.log('Shipment fields:', Object.keys(data.fields))\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fshipments\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`, `boolean`, `datetime`, `array` |\n| `data.fields.\u003Cfield>.readonly` | boolean | `true` means the field is set by the system; writing to it 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` |\n| `data.fields.\u003Cfield>.itemSchema` | object | Present only on arrays — the schema of an array element |\n| `data.fields.\u003Cfield>.label` | string | Short field name |\n| `data.fields.\u003Cfield>.description` | string | Field explanation |\n| `data.aggregatable` | array | Fields allowed for `groupBy` grouping in [shipment aggregation](.\u002Faggregate.md) |\n| `data.batch` | array | Operations available in batch calls. For shipments the array is empty |\n\n### Shipment fields\n\nThe full set of fields returned by `GET \u002Fv1\u002Fshipments\u002Ffields`. The RO column marks read-only fields.\n\n| Field | Type | RO | Description |\n|------|-----|:--:|---------|\n| `id` | number | yes | Shipment ID |\n| `orderId` | number | no | Order ID. List: [`GET \u002Fv1\u002Forders`](\u002Fdocs\u002Fentities\u002Forders\u002Flist). Required at creation. Set only at creation: on update it is rejected with `400 READONLY_FIELD`, marked `readonlyOnUpdate` in the schema |\n| `accountNumber` | string | yes | Shipment number: the order number and the shipment sequence number separated by `\u002F`, for example `1027\u002F2` |\n| `deliveryId` | number | no | Delivery service ID. List: [`GET \u002Fv1\u002Fdelivery-services`](\u002Fdocs\u002Fentities\u002Fdelivery-services\u002Flist). Required at creation |\n| `deliveryName` | string | yes | Delivery service name |\n| `deliveryXmlId` | string | yes | External code of the delivery service. `null` if not set |\n| `statusId` | string | no | Delivery status. List: [`GET \u002Fv1\u002Forder-statuses?filter[type]=D`](\u002Fdocs\u002Fentities\u002Forder-statuses\u002Flist) |\n| `statusXmlId` | string | yes | External code of the delivery status. `null` if not set |\n| `allowDelivery` | boolean | no | Whether delivery is allowed |\n| `dateAllowDelivery` | datetime | yes | Date delivery was allowed. `null` until delivery is allowed |\n| `empAllowDeliveryId` | number | yes | ID of the employee who allowed delivery. `null` until delivery is allowed |\n| `deducted` | boolean | yes | The \"shipped\" mark. Set via [`POST \u002Fv1\u002Fshipments\u002F:id\u002Fship`](.\u002Fship.md), cleared via [`POST \u002Fv1\u002Fshipments\u002F:id\u002Funship`](.\u002Funship.md) |\n| `dateDeducted` | datetime | yes | Date the \"shipped\" mark last changed — when it was set or cleared. `null` until the mark is first set |\n| `empDeductedId` | number | yes | ID of the employee who last changed the \"shipped\" mark. `null` until the mark is first set |\n| `reasonUndoDeducted` | string | yes | Reason the \"shipped\" mark was cleared. Stays `null` when the mark is cleared through [`unship`](.\u002Funship.md) |\n| `canceled` | boolean | yes | Whether the shipment is canceled |\n| `dateCanceled` | datetime | yes | Cancellation date. `null` if the shipment is not canceled |\n| `empCanceledId` | number | yes | ID of the employee who canceled the shipment. `null` if the shipment is not canceled |\n| `marked` | boolean | yes | Whether the shipment is marked as problematic |\n| `dateMarked` | datetime | yes | Date of the mark. `null` if there is no mark |\n| `empMarkedId` | number | yes | ID of the employee who set the mark. `null` if there is no mark |\n| `reasonMarked` | string | yes | Reason for the mark. `null` if there is no mark |\n| `responsibleId` | number | no | Responsible employee. List: [`GET \u002Fv1\u002Fusers`](\u002Fdocs\u002Fentities\u002Fusers\u002Flist) |\n| `dateResponsibleId` | datetime | yes | Date the responsible employee was assigned |\n| `empResponsibleId` | number | yes | ID of the employee who assigned the responsible employee |\n| `priceDelivery` | number | no | Delivery cost |\n| `basePriceDelivery` | number | no | Base delivery cost |\n| `discountPrice` | number | yes | Delivery discount |\n| `customPriceDelivery` | boolean | yes | Whether the delivery cost is set manually |\n| `currency` | string | yes | Shipment currency, for example `USD` |\n| `companyId` | number | no | CRM company ID from [`GET \u002Fv1\u002Fcompanies`](\u002Fdocs\u002Fentities\u002Fcompanies\u002Flist). `null` if no company is set |\n| `deliveryDocNum` | string | no | Shipment document number. `null` if not set |\n| `deliveryDocDate` | datetime | no | Shipment document date. `null` if not set |\n| `trackingNumber` | string | no | Tracking number |\n| `trackingStatus` | string | yes | Parcel tracking status. `null` if there is no tracking |\n| `trackingDescription` | string | yes | Tracking status description. `null` if there is no tracking |\n| `trackingLastCheck` | string | yes | Time of the last tracking status check. `null` if there was no check |\n| `externalDelivery` | boolean | yes | External delivery flag |\n| `system` | boolean | yes | System shipment of the order. Details — [Shipments](\u002Fdocs\u002Fentities\u002Fshipments) |\n| `comments` | string | no | Shipment comment |\n| `xmlId` | string | no | External code of the shipment |\n| `id1c` | string | yes | Identifier in the ERP system. `null` if the shipment is not synchronized with an ERP system |\n| `version1c` | string | yes | Version in the ERP system. `null` if the shipment is not synchronized with an ERP system |\n| `updated1c` | boolean | yes | Whether the shipment was updated through the ERP system |\n| `dateInsert` | datetime | yes | Creation date |\n| `shipmentItems` | array | yes | Shipment items. Returned in the [`GET \u002Fv1\u002Fshipments\u002F:id`](.\u002Fget.md) response, managed via [shipment items](\u002Fdocs\u002Fentities\u002Fshipment-items) |\n\n## Response example\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"fields\": {\n      \"accountNumber\": {\n        \"type\": \"string\",\n        \"readonly\": true,\n        \"label\": \"accountNumber\",\n        \"description\": \"Bitrix24 accountNumber field.\"\n      },\n      \"allowDelivery\": {\n        \"type\": \"boolean\",\n        \"readonly\": false,\n        \"label\": \"Delivery allowed\",\n        \"description\": \"Delivery allowed.\"\n      },\n      \"basePriceDelivery\": {\n        \"type\": \"number\",\n        \"readonly\": false,\n        \"label\": \"Base delivery price\",\n        \"description\": \"Base delivery price.\"\n      },\n      \"canceled\": {\n        \"type\": \"boolean\",\n        \"readonly\": true,\n        \"label\": \"canceled\",\n        \"description\": \"Bitrix24 canceled field.\"\n      },\n      \"comments\": {\n        \"type\": \"string\",\n        \"readonly\": false,\n        \"label\": \"Comment\",\n        \"description\": \"Comment.\"\n      },\n      \"companyId\": {\n        \"type\": \"number\",\n        \"readonly\": false,\n        \"label\": \"Company ID\",\n        \"description\": \"Company ID.\"\n      },\n      \"currency\": {\n        \"type\": \"string\",\n        \"readonly\": true,\n        \"label\": \"currency\",\n        \"description\": \"Bitrix24 currency field.\"\n      },\n      \"customPriceDelivery\": {\n        \"type\": \"boolean\",\n        \"readonly\": true,\n        \"label\": \"Manual delivery price\",\n        \"description\": \"Manual delivery price.\"\n      },\n      \"dateAllowDelivery\": {\n        \"type\": \"datetime\",\n        \"readonly\": true,\n        \"label\": \"dateAllowDelivery\",\n        \"description\": \"Bitrix24 dateAllowDelivery field.\"\n      },\n      \"dateCanceled\": {\n        \"type\": \"datetime\",\n        \"readonly\": true,\n        \"label\": \"dateCanceled\",\n        \"description\": \"Bitrix24 dateCanceled field.\"\n      },\n      \"dateDeducted\": {\n        \"type\": \"datetime\",\n        \"readonly\": true,\n        \"label\": \"dateDeducted\",\n        \"description\": \"Bitrix24 dateDeducted field.\"\n      },\n      \"dateInsert\": {\n        \"type\": \"datetime\",\n        \"readonly\": true,\n        \"label\": \"Creation date\",\n        \"description\": \"Creation date.\"\n      },\n      \"dateMarked\": {\n        \"type\": \"datetime\",\n        \"readonly\": true,\n        \"label\": \"dateMarked\",\n        \"description\": \"Bitrix24 dateMarked field.\"\n      },\n      \"dateResponsibleId\": {\n        \"type\": \"datetime\",\n        \"readonly\": true,\n        \"label\": \"dateResponsibleId\",\n        \"description\": \"Bitrix24 dateResponsibleId field.\"\n      },\n      \"deducted\": {\n        \"type\": \"boolean\",\n        \"readonly\": true,\n        \"label\": \"Shipped\",\n        \"description\": \"Shipped mark; use POST \u002Fv1\u002Fshipments\u002F:id\u002Fship or \u002Funship. Warehouse accounting can deduct stock.\"\n      },\n      \"deliveryDocDate\": {\n        \"type\": \"datetime\",\n        \"readonly\": false,\n        \"label\": \"Delivery document date\",\n        \"description\": \"Delivery document date.\"\n      },\n      \"deliveryDocNum\": {\n        \"type\": \"string\",\n        \"readonly\": false,\n        \"label\": \"Delivery document number\",\n        \"description\": \"Delivery document number.\"\n      },\n      \"deliveryId\": {\n        \"type\": \"number\",\n        \"readonly\": false,\n        \"required\": true,\n        \"label\": \"Delivery service ID\",\n        \"description\": \"Delivery service ID from GET \u002Fv1\u002Fdelivery-services; see \u002Fdocs\u002Fentities\u002Fdelivery-services.\"\n      },\n      \"deliveryName\": {\n        \"type\": \"string\",\n        \"readonly\": true,\n        \"label\": \"deliveryName\",\n        \"description\": \"Bitrix24 deliveryName field.\"\n      },\n      \"deliveryXmlId\": {\n        \"type\": \"string\",\n        \"readonly\": true,\n        \"label\": \"deliveryXmlId\",\n        \"description\": \"Bitrix24 deliveryXmlId field.\"\n      },\n      \"discountPrice\": {\n        \"type\": \"number\",\n        \"readonly\": true,\n        \"label\": \"discountPrice\",\n        \"description\": \"Bitrix24 discountPrice field.\"\n      },\n      \"empAllowDeliveryId\": {\n        \"type\": \"number\",\n        \"readonly\": true,\n        \"label\": \"empAllowDeliveryId\",\n        \"description\": \"Bitrix24 empAllowDeliveryId field.\"\n      },\n      \"empCanceledId\": {\n        \"type\": \"number\",\n        \"readonly\": true,\n        \"label\": \"empCanceledId\",\n        \"description\": \"Bitrix24 empCanceledId field.\"\n      },\n      \"empDeductedId\": {\n        \"type\": \"number\",\n        \"readonly\": true,\n        \"label\": \"empDeductedId\",\n        \"description\": \"Bitrix24 empDeductedId field.\"\n      },\n      \"empMarkedId\": {\n        \"type\": \"number\",\n        \"readonly\": true,\n        \"label\": \"empMarkedId\",\n        \"description\": \"Bitrix24 empMarkedId field.\"\n      },\n      \"empResponsibleId\": {\n        \"type\": \"number\",\n        \"readonly\": true,\n        \"label\": \"empResponsibleId\",\n        \"description\": \"Bitrix24 empResponsibleId field.\"\n      },\n      \"externalDelivery\": {\n        \"type\": \"boolean\",\n        \"readonly\": true,\n        \"label\": \"externalDelivery\",\n        \"description\": \"Bitrix24 externalDelivery field.\"\n      },\n      \"id\": {\n        \"type\": \"number\",\n        \"readonly\": true,\n        \"label\": \"Shipment ID\",\n        \"description\": \"Shipment ID.\"\n      },\n      \"id1c\": {\n        \"type\": \"string\",\n        \"readonly\": true,\n        \"label\": \"id1c\",\n        \"description\": \"Bitrix24 id1c field.\"\n      },\n      \"marked\": {\n        \"type\": \"boolean\",\n        \"readonly\": true,\n        \"label\": \"marked\",\n        \"description\": \"Bitrix24 marked field.\"\n      },\n      \"orderId\": {\n        \"type\": \"number\",\n        \"readonly\": false,\n        \"readonlyOnUpdate\": true,\n        \"required\": true,\n        \"label\": \"Order ID\",\n        \"description\": \"Order ID. Lookup: GET \u002Fv1\u002Forders.\"\n      },\n      \"priceDelivery\": {\n        \"type\": \"number\",\n        \"readonly\": false,\n        \"label\": \"Delivery price\",\n        \"description\": \"Delivery price.\"\n      },\n      \"reasonMarked\": {\n        \"type\": \"string\",\n        \"readonly\": true,\n        \"label\": \"reasonMarked\",\n        \"description\": \"Bitrix24 reasonMarked field.\"\n      },\n      \"reasonUndoDeducted\": {\n        \"type\": \"string\",\n        \"readonly\": true,\n        \"label\": \"reasonUndoDeducted\",\n        \"description\": \"Bitrix24 reasonUndoDeducted field.\"\n      },\n      \"responsibleId\": {\n        \"type\": \"number\",\n        \"readonly\": false,\n        \"label\": \"Responsible user ID\",\n        \"description\": \"Responsible user ID.\"\n      },\n      \"statusId\": {\n        \"type\": \"string\",\n        \"readonly\": false,\n        \"label\": \"statusId\",\n        \"description\": \"Bitrix24 statusId field.\"\n      },\n      \"statusXmlId\": {\n        \"type\": \"string\",\n        \"readonly\": true,\n        \"label\": \"statusXmlId\",\n        \"description\": \"Bitrix24 statusXmlId field.\"\n      },\n      \"system\": {\n        \"type\": \"boolean\",\n        \"readonly\": true,\n        \"label\": \"System shipment\",\n        \"description\": \"System shipment.\"\n      },\n      \"trackingDescription\": {\n        \"type\": \"string\",\n        \"readonly\": true,\n        \"label\": \"trackingDescription\",\n        \"description\": \"Bitrix24 trackingDescription field.\"\n      },\n      \"trackingLastCheck\": {\n        \"type\": \"string\",\n        \"readonly\": true,\n        \"label\": \"trackingLastCheck\",\n        \"description\": \"Bitrix24 trackingLastCheck field.\"\n      },\n      \"trackingNumber\": {\n        \"type\": \"string\",\n        \"readonly\": false,\n        \"label\": \"Tracking number\",\n        \"description\": \"Tracking number.\"\n      },\n      \"trackingStatus\": {\n        \"type\": \"string\",\n        \"readonly\": true,\n        \"label\": \"trackingStatus\",\n        \"description\": \"Bitrix24 trackingStatus field.\"\n      },\n      \"updated1c\": {\n        \"type\": \"boolean\",\n        \"readonly\": true,\n        \"label\": \"updated1c\",\n        \"description\": \"Bitrix24 updated1c field.\"\n      },\n      \"version1c\": {\n        \"type\": \"string\",\n        \"readonly\": true,\n        \"label\": \"version1c\",\n        \"description\": \"Bitrix24 version1c field.\"\n      },\n      \"xmlId\": {\n        \"type\": \"string\",\n        \"readonly\": false,\n        \"label\": \"External code\",\n        \"description\": \"External code.\"\n      },\n      \"shipmentItems\": {\n        \"type\": \"array\",\n        \"readonly\": true,\n        \"label\": \"Shipment positions\",\n        \"description\": \"Positions returned by get; manage via \u002Fv1\u002Fshipment-items.\",\n        \"itemSchema\": {\n          \"type\": \"object\"\n        }\n      }\n    },\n    \"aggregatable\": [\n      \"orderId\",\n      \"priceDelivery\",\n      \"deliveryId\"\n    ],\n    \"batch\": []\n  }\n}\n```\n\n## Error response example\n\n401 — no API key was provided:\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| 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` | 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- [List shipments](.\u002Flist.md)\n- [Get a shipment](.\u002Fget.md)\n- [Create a shipment](.\u002Fcreate.md)\n- [Shipment aggregation](.\u002Faggregate.md)\n- [Shipments](\u002Fdocs\u002Fentities\u002Fshipments)\n- [Shipment items](\u002Fdocs\u002Fentities\u002Fshipment-items)\n- [Entity reference](\u002Fdocs\u002Fentity-api)\n","## Shipment aggregation\n\n`POST \u002Fv1\u002Fshipments\u002Faggregate`\n\nCounts shipments and computes the sum, average, minimum and maximum of the delivery cost, with filtering and grouping by order or delivery service.\n\n## Standard fields\n\n| Field | Purpose |\n|------|------------|\n| `priceDelivery` | Delivery cost — the main field for `sum` \u002F `avg` \u002F `min` \u002F `max`. Also available for `groupBy` |\n| `basePriceDelivery`, `discountPrice` | Base delivery cost and delivery discount — numeric fields for `sum` \u002F `avg` \u002F `min` \u002F `max` |\n| `orderId` | Order ID — used in `groupBy` to break shipments down by order |\n| `deliveryId` | Delivery service ID — used in `groupBy` to break shipments down by service |\n\nThe fields available for `groupBy` are listed in the `aggregatable` array in [`GET \u002Fv1\u002Fshipments\u002Ffields`](.\u002Ffields.md). Numeric functions accept any field of type `number` from the same schema, including fields outside `aggregatable`.\n\n**User fields.** For a non-existent field name in `sum` \u002F `avg` \u002F `min` \u002F `max`, the `400 INVALID_PARAMS` response lists the allowed numeric fields. That list contains only standard shipment fields — `basePriceDelivery`, `companyId`, `deliveryId`, `discountPrice`, `empAllowDeliveryId`, `empCanceledId`, `empDeductedId`, `empMarkedId`, `empResponsibleId`, `id`, `orderId`, `priceDelivery`, `responsibleId`, with no user fields. A rejection for a field outside `aggregatable` in `groupBy` names only `orderId`, `priceDelivery`, `deliveryId` as allowed.\n\n## Request fields (body)\n\n| Field | Type | Required | Description |\n|------|-----|:-----:|---------|\n| `aggregate` | array | no | Array of expressions `{ \"field\": \"priceDelivery\", \"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\u002Fshipments\u002Ffields`](.\u002Ffields.md).\u003Cbr>[Filtering syntax](\u002Fdocs\u002Ffiltering). Example: `{ \"orderId\": 1027 }` |\n| `groupBy` | string \\| string[] | no | A field or an array of fields to group by, up to 5 fields. Allowed values come from the `aggregatable` array: `orderId`, `priceDelivery`, `deliveryId` |\n| `groupOrderBy` | array | no | Group sorting: `[{ \"field\": \"priceDelivery:sum\", \"direction\": \"desc\" }]`. `field` accepts `count`, a field name from `groupBy`, or `\u003Cfield>:\u003Cfunction>` from `aggregate`. Works only together with `groupBy` |\n| `groupLimit` | number | no | Limits 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\u002Fshipments\u002Faggregate\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"filter\": { \"orderId\": 1027 },\n    \"aggregate\": [\n      { \"field\": \"*\", \"function\": \"count\" },\n      { \"field\": \"priceDelivery\", \"function\": \"sum\" },\n      { \"field\": \"priceDelivery\", \"function\": \"avg\" }\n    ],\n    \"groupBy\": \"deliveryId\"\n  }'\n```\n\n### curl — OAuth application\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fshipments\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\": { \"orderId\": 1027 },\n    \"aggregate\": [\n      { \"field\": \"*\", \"function\": \"count\" },\n      { \"field\": \"priceDelivery\", \"function\": \"sum\" },\n      { \"field\": \"priceDelivery\", \"function\": \"avg\" }\n    ],\n    \"groupBy\": \"deliveryId\"\n  }'\n```\n\n### JavaScript — personal key\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fshipments\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: { orderId: 1027 },\n    aggregate: [\n      { field: '*', function: 'count' },\n      { field: 'priceDelivery', function: 'sum' },\n      { field: 'priceDelivery', function: 'avg' },\n    ],\n    groupBy: 'deliveryId',\n  }),\n})\n\nconst { success, data } = await res.json()\n\u002F\u002F data.groups — delivery cost by delivery service\nconsole.log(data.groups)\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fshipments\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: { orderId: 1027 },\n    aggregate: [\n      { field: '*', function: 'count' },\n      { field: 'priceDelivery', function: 'sum' },\n      { field: 'priceDelivery', function: 'avg' },\n    ],\n    groupBy: 'deliveryId',\n  }),\n})\n\nconst { success, data } = await res.json()\n```\n\n## Other scenarios\n\nThe blocks below are request bodies.\n\nShipment count for an order only — without the `aggregate` array no records are fetched, and `data.meta.recordsProcessed` in the response is `0`:\n\n```json\n{ \"filter\": { \"orderId\": 1027 } }\n```\n\nGrouping by two fields — by order and delivery service:\n\n```json\n{\n  \"aggregate\": [{ \"field\": \"*\", \"function\": \"count\" }],\n  \"groupBy\": [\"orderId\", \"deliveryId\"]\n}\n```\n\nSum and average of the delivery cost without grouping:\n\n```json\n{\n  \"filter\": { \"orderId\": 1027 },\n  \"aggregate\": [\n    { \"field\": \"*\", \"function\": \"count\" },\n    { \"field\": \"priceDelivery\", \"function\": \"sum\" },\n    { \"field\": \"priceDelivery\", \"function\": \"avg\" }\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 shipments matching the filter |\n| `data.aggregates` | object | Results of numeric functions by field: `{ \"priceDelivery\": { \"sum\": 500, \"avg\": 500 } }`. An empty object if `aggregate` contains only `count` |\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 processed records, 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 size of the shortfall arrives in `data.meta.recordsShortfall`, the cut-short slice in `data.meta.pageErrorSample`. Always present, `false` on a complete response. If the request has neither `groupBy` nor numeric functions, no records are fetched 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\": 1,\n    \"aggregates\": {\n      \"priceDelivery\": {\n        \"sum\": 500,\n        \"avg\": 500\n      }\n    },\n    \"groups\": [\n      {\n        \"deliveryId\": 1,\n        \"count\": 1,\n        \"aggregates\": {\n          \"priceDelivery\": {\n            \"sum\": 500,\n            \"avg\": 500\n          }\n        }\n      }\n    ],\n    \"meta\": {\n      \"totalRecords\": 1,\n      \"recordsProcessed\": 1,\n      \"truncated\": false,\n      \"groupTotal\": 1,\n      \"groupsTruncated\": false\n    }\n  }\n}\n```\n\n## Error response example\n\n400 — the field is not in the schema. 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: basePriceDelivery, companyId, deliveryId, discountPrice, empAllowDeliveryId, empCanceledId, empDeductedId, empMarkedId, empResponsibleId, id, orderId, priceDelivery, responsibleId.\"\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` has 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 `trackingNumber` — 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 `op`, `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 — the message contains the list of allowed ones |\n| 400 | `INVALID_PARAMS` | `groupBy` has 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 its value is invalid |\n| 400 | `UNKNOWN_FILTER_FIELD` | Unknown field in `filter` — the message contains the list of shipment 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`, an empty object in a condition value, or the `$or` logical condition |\n| 400 | `INVALID_FILTER_SHAPE` | `filter` is not an object of conditions, for example a string, a number or an array |\n| 400 | `INVALID_DUPLICATE_FILTER_FIELD` | Two filter conditions reduce to one Bitrix24 condition, for example `$ne` and `$nin` on the same field. Pass only one of them |\n| 403 | `SCOPE_DENIED` | The API key has no `sale` scope |\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: 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**`count` versus numeric functions.** A request without `groupBy` and without numeric functions is handled by a single request to Bitrix24 — no records are fetched, and the response time does not depend on the number of shipments. As soon as the request has `sum` \u002F `avg` \u002F `min` \u002F `max` or `groupBy`, including together with a single `count`, up to 5000 records are loaded page by page, and the aggregates are computed by Vibecode. With `meta.truncated: true`, the `truncated: true` mark is also set inside the object of each field 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 selection, use a request without `groupBy` and numeric functions, or narrow the filter, for example by `orderId`. For a full explanation, see [Aggregation POST — the 5000-record ceiling](\u002Fdocs\u002Fentity-api#aggregation-post-the-5000-record-ceiling).\n\n## See also\n\n- [List shipments](.\u002Flist.md)\n- [Search shipments](.\u002Fsearch.md)\n- [Shipment fields](.\u002Ffields.md)\n- [Shipments](\u002Fdocs\u002Fentities\u002Fshipments)\n- [Filtering syntax](\u002Fdocs\u002Ffiltering)\n- [Limits and optimization](\u002Fdocs\u002Foptimization)\n","## Set the \"shipped\" mark\n\n`POST \u002Fv1\u002Fshipments\u002F:id\u002Fship`\n\nSets the \"shipped\" mark on an online store order shipment. Call it once the goods are handed over for delivery.\n\n## Parameters\n\n| Parameter | Type | Required | Description |\n|----------|-----|:-----:|---------|\n| `id` (path) | number | yes | Shipment ID, a positive integer. List: [`GET \u002Fv1\u002Fshipments`](.\u002Flist.md) |\n\nPass an empty object `{}` with the `Content-Type: application\u002Fjson` header, or send the request with no body and without this header.\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fshipments\u002F1205\u002Fship\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{}'\n```\n\n### curl — OAuth application\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fshipments\u002F1205\u002Fship\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{}'\n```\n\n### JavaScript — personal key\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fshipments\u002F1205\u002Fship', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: '{}',\n})\n\nconst { success, data } = await res.json()\nconsole.log('Shipped:', data.deducted, '— mark date:', data.dateDeducted)\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fshipments\u002F1205\u002Fship', {\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: '{}',\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 shipment with all fields as they are after the mark is set. See [Shipment fields](.\u002Ffields.md) |\n| `data.deducted` | boolean | Always `true` in a successful response |\n| `data.dateDeducted` | datetime | Date the mark was set |\n| `data.empDeductedId` | number | ID of the employee who set the mark. List: [`GET \u002Fv1\u002Fusers`](\u002Fdocs\u002Fentities\u002Fusers\u002Flist) |\n\n## Response example\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"accountNumber\": \"1027\u002F2\",\n    \"allowDelivery\": true,\n    \"basePriceDelivery\": 500,\n    \"canceled\": false,\n    \"comments\": \"Test shipment for documentation\",\n    \"companyId\": null,\n    \"currency\": \"USD\",\n    \"customPriceDelivery\": false,\n    \"dateAllowDelivery\": \"2026-10-06T11:31:17.000Z\",\n    \"dateCanceled\": null,\n    \"dateDeducted\": \"2026-10-06T16:44:20.000Z\",\n    \"dateInsert\": \"2026-10-06T11:30:44.000Z\",\n    \"dateMarked\": null,\n    \"dateResponsibleId\": \"2026-10-06T11:30:44.000Z\",\n    \"deducted\": true,\n    \"deliveryDocDate\": null,\n    \"deliveryDocNum\": \"WB-1205\",\n    \"deliveryId\": 1,\n    \"deliveryName\": \"Courier delivery\",\n    \"deliveryXmlId\": null,\n    \"discountPrice\": 0,\n    \"empAllowDeliveryId\": 1317,\n    \"empCanceledId\": null,\n    \"empDeductedId\": 1317,\n    \"empMarkedId\": null,\n    \"empResponsibleId\": 1317,\n    \"externalDelivery\": false,\n    \"id\": 1205,\n    \"id1c\": null,\n    \"marked\": false,\n    \"orderId\": 1027,\n    \"priceDelivery\": 500,\n    \"reasonMarked\": null,\n    \"reasonUndoDeducted\": null,\n    \"responsibleId\": 1295,\n    \"shipmentItems\": [],\n    \"statusId\": \"DN\",\n    \"statusXmlId\": null,\n    \"system\": false,\n    \"trackingDescription\": null,\n    \"trackingLastCheck\": null,\n    \"trackingNumber\": \"VIBE-DOC-3\",\n    \"trackingStatus\": null,\n    \"updated1c\": false,\n    \"version1c\": null,\n    \"xmlId\": \"bx_6ac4cdd46e442\"\n  }\n}\n```\n\n## Error response example\n\n400 — a field was passed in the request body:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"INVALID_PARAMS\",\n    \"message\": \"This action takes an empty body.\"\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|------|-----|---------|\n| 400 | `INVALID_ID` | The `id` in the path is not a positive integer. Error message: `Shipment ID must be a positive integer.` |\n| 400 | `INVALID_PARAMS` | The request body is not empty or is not an object. Error message: `This action takes an empty body.` |\n| 404 | `ENTITY_NOT_FOUND` | No shipment with this `id` exists. Error message: `shipment is not exists` |\n| 422 | `BITRIX_NO_EFFECT` | Bitrix24 did not confirm the mark change. Error message: `Bitrix24 did not confirm the shipped mark change.` |\n| 422 | `BITRIX_NO_EFFECT` | The mark was set, but the shipment could not be re-read. Error message: `Bitrix24 did not return the shipment after the action.` |\n| 422 | `BITRIX_NO_EFFECT` | The shipment was re-read, but its `deducted` is not `true`. Error message: `Bitrix24 did not persist the requested shipped mark.` |\n| 422 | `BITRIX_ERROR` | Bitrix24 rejected the mark. 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| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |\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**Inventory management.** If inventory management is enabled on the Bitrix24 account, the mark may write off stock for the products in the [shipment items](\u002Fdocs\u002Fentities\u002Fshipment-items).\n\n**A repeated call changes nothing.** For a shipment that already has the mark, the request returns `200` with the same shipment. `dateDeducted` and `empDeductedId` keep their values from the first mark. So after `422 BITRIX_NO_EFFECT` you can repeat the request or check `deducted` via [`GET \u002Fv1\u002Fshipments\u002F:id`](.\u002Fget.md).\n\n**A shipment with the mark cannot be deleted.** [`DELETE \u002Fv1\u002Fshipments\u002F:id`](.\u002Fdelete.md) returns `422 BITRIX_ERROR` while the mark is set. Clear it via [`POST \u002Fv1\u002Fshipments\u002F:id\u002Funship`](.\u002Funship.md) before deleting.\n\n## See also\n\n- [Clear the \"shipped\" mark](.\u002Funship.md)\n- [Get a shipment](.\u002Fget.md)\n- [Delete a shipment](.\u002Fdelete.md)\n- [Shipment fields](.\u002Ffields.md)\n- [Shipment items](\u002Fdocs\u002Fentities\u002Fshipment-items)\n- [Shipments](\u002Fdocs\u002Fentities\u002Fshipments)\n","## Clear the \"shipped\" mark\n\n`POST \u002Fv1\u002Fshipments\u002F:id\u002Funship`\n\nClears the \"shipped\" mark from an online store order shipment, for example before deleting the shipment or after setting the mark by mistake.\n\n## Parameters\n\n| Parameter | Type | Required | Description |\n|----------|-----|:-----:|---------|\n| `id` (path) | number | yes | Shipment ID, a positive integer. List: [`GET \u002Fv1\u002Fshipments`](.\u002Flist.md) |\n\nPass an empty object `{}` with the `Content-Type: application\u002Fjson` header, or send the request with no body and without this header.\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fshipments\u002F1205\u002Funship\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{}'\n```\n\n### curl — OAuth application\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fshipments\u002F1205\u002Funship\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{}'\n```\n\n### JavaScript — personal key\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fshipments\u002F1205\u002Funship', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: '{}',\n})\n\nconst { success, data } = await res.json()\nconsole.log('Shipped:', data.deducted)\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fshipments\u002F1205\u002Funship', {\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: '{}',\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 shipment with all fields as they are after the mark is cleared. See [Shipment fields](.\u002Ffields.md) |\n| `data.deducted` | boolean | Always `false` in a successful response |\n| `data.dateDeducted` | datetime | Date the mark was cleared. The field is not reset |\n| `data.empDeductedId` | number | ID of the employee who last changed the mark. The field is not reset. List: [`GET \u002Fv1\u002Fusers`](\u002Fdocs\u002Fentities\u002Fusers\u002Flist) |\n| `data.reasonUndoDeducted` | string | Stays `null`: the method does not accept a reason for clearing the mark |\n\n## Response example\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"accountNumber\": \"1027\u002F2\",\n    \"allowDelivery\": true,\n    \"basePriceDelivery\": 500,\n    \"canceled\": false,\n    \"comments\": \"Test shipment for documentation\",\n    \"companyId\": null,\n    \"currency\": \"USD\",\n    \"customPriceDelivery\": false,\n    \"dateAllowDelivery\": \"2026-10-06T11:31:17.000Z\",\n    \"dateCanceled\": null,\n    \"dateDeducted\": \"2026-10-06T16:45:13.000Z\",\n    \"dateInsert\": \"2026-10-06T11:30:44.000Z\",\n    \"dateMarked\": null,\n    \"dateResponsibleId\": \"2026-10-06T11:30:44.000Z\",\n    \"deducted\": false,\n    \"deliveryDocDate\": null,\n    \"deliveryDocNum\": \"WB-1205\",\n    \"deliveryId\": 1,\n    \"deliveryName\": \"Courier delivery\",\n    \"deliveryXmlId\": null,\n    \"discountPrice\": 0,\n    \"empAllowDeliveryId\": 1317,\n    \"empCanceledId\": null,\n    \"empDeductedId\": 1317,\n    \"empMarkedId\": null,\n    \"empResponsibleId\": 1317,\n    \"externalDelivery\": false,\n    \"id\": 1205,\n    \"id1c\": null,\n    \"marked\": false,\n    \"orderId\": 1027,\n    \"priceDelivery\": 500,\n    \"reasonMarked\": null,\n    \"reasonUndoDeducted\": null,\n    \"responsibleId\": 1295,\n    \"shipmentItems\": [],\n    \"statusId\": \"DN\",\n    \"statusXmlId\": null,\n    \"system\": false,\n    \"trackingDescription\": null,\n    \"trackingLastCheck\": null,\n    \"trackingNumber\": \"VIBE-DOC-3\",\n    \"trackingStatus\": null,\n    \"updated1c\": false,\n    \"version1c\": null,\n    \"xmlId\": \"bx_6ac4cdd46e442\"\n  }\n}\n```\n\n## Error response example\n\n404 — shipment not found:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"ENTITY_NOT_FOUND\",\n    \"message\": \"shipment is not exists\"\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|------|-----|---------|\n| 400 | `INVALID_ID` | The `id` in the path is not a positive integer. Error message: `Shipment ID must be a positive integer.` |\n| 400 | `INVALID_PARAMS` | The request body is not empty or is not an object. Error message: `This action takes an empty body.` |\n| 404 | `ENTITY_NOT_FOUND` | No shipment with this `id` exists. Error message: `shipment is not exists` |\n| 422 | `BITRIX_NO_EFFECT` | Bitrix24 did not confirm the mark change. Error message: `Bitrix24 did not confirm the shipped mark change.` |\n| 422 | `BITRIX_NO_EFFECT` | The mark was cleared, but the shipment could not be re-read. Error message: `Bitrix24 did not return the shipment after the action.` |\n| 422 | `BITRIX_NO_EFFECT` | The shipment was re-read, but its `deducted` is not `false`. Error message: `Bitrix24 did not persist the requested shipped mark.` |\n| 422 | `BITRIX_ERROR` | Bitrix24 rejected clearing the mark. 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| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |\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**A repeated call changes nothing.** For a shipment without the mark, the request returns `200` with the same shipment. So after `422 BITRIX_NO_EFFECT`, you can retry the request or check `deducted` via [`GET \u002Fv1\u002Fshipments\u002F:id`](.\u002Fget.md).\n\n## See also\n\n- [Set the \"shipped\" mark](.\u002Fship.md)\n- [Get a shipment](.\u002Fget.md)\n- [Delete a shipment](.\u002Fdelete.md)\n- [Shipment fields](.\u002Ffields.md)\n- [Shipment items](\u002Fdocs\u002Fentities\u002Fshipment-items)\n- [Shipments](\u002Fdocs\u002Fentities\u002Fshipments)\n",1795000377353]