لوكلاء AI: ملف markdown لهذه الصفحة — /docs-content-en/entities/shipments.md فهرس التوثيق — /llms.txt

مقالات التوثيق متاحة حاليًا باللغة الإنجليزية فقط.

Shipments

Online store order shipments: delivery service, delivery cost, tracking number, shipping document and the "shipped" mark.

Bitrix24 API: sale.shipment.* Scope: sale

Create a shipment

POST /v1/shipments

Creates a shipment in an existing online store order and assigns a delivery service to it.

Fields are passed flat at the JSON root, without a fields wrapper.

Request fields (body)

Field Type Required Description
FieldorderId Typenumber Requiredyes DescriptionID of the order in which the shipment is created. List: GET /v1/orders. Cannot be changed after creation
FielddeliveryId Typenumber Requiredyes DescriptionDelivery service ID. List: GET /v1/delivery-services
FieldallowDelivery Typeboolean Requiredno DescriptionWhether delivery is allowed. If omitted, the shipment is created with false
FieldstatusId Typestring Requiredno DescriptionDelivery status. List: GET /v1/order-statuses?filter[type]=D. If omitted, the shipment gets the Bitrix24 account's initial delivery status, DN in the example below
FieldtrackingNumber Typestring Requiredno DescriptionTracking number
FielddeliveryDocNum Typestring Requiredno DescriptionShipment document number
FielddeliveryDocDate Typedatetime Requiredno DescriptionShipment document date
FieldpriceDelivery Typenumber Requiredno DescriptionDelivery price. If omitted, the delivery service price is used
FieldbasePriceDelivery Typenumber Requiredno DescriptionBase delivery price
FieldresponsibleId Typenumber Requiredno DescriptionID of the responsible employee. List: GET /v1/users. If omitted, the responsible person is assigned automatically
FieldcompanyId Typenumber Requiredno DescriptionCRM company ID. List: GET /v1/companies. The company's existence is not checked
Fieldcomments Typestring Requiredno DescriptionShipment comment
FieldxmlId Typestring Requiredno DescriptionExternal code. If omitted, it is generated automatically

Full field list — GET /v1/shipments/fields.

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/shipments" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": 1027,
    "deliveryId": 1,
    "trackingNumber": "VIBE-DOC-1",
    "comments": "Test shipment for documentation"
  }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/shipments" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": 1027,
    "deliveryId": 1,
    "trackingNumber": "VIBE-DOC-1",
    "comments": "Test shipment for documentation"
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/shipments', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    orderId: 1027,
    deliveryId: 1,
    trackingNumber: 'VIBE-DOC-1',
    comments: 'Test shipment for documentation',
  }),
})

const { success, data } = await res.json()
console.log('Shipment ID:', data.id)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/shipments', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    orderId: 1027,
    deliveryId: 1,
    trackingNumber: 'VIBE-DOC-1',
    comments: 'Test shipment for documentation',
  }),
})

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

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue on success. The response HTTP status is 201
Fielddata Typeobject DescriptionThe created shipment with all fields — Shipment fields
Fielddata.id Typenumber DescriptionID of the created shipment
Fielddata.accountNumber Typestring DescriptionShipment number: the order number and the shipment's sequence number separated by /
Fielddata.deducted Typeboolean DescriptionThe "shipped" mark. Always false for a new shipment
Fielddata.deliveryName Typestring DescriptionName of the delivery service from deliveryId
Fielddata.shipmentItems Typearray DescriptionShipment items. An empty array if no items have been added yet
Fielddata.system Typeboolean DescriptionSystem shipment. Always false for a shipment created via the API

Response example

JSON 
{
  "success": true,
  "data": {
    "accountNumber": "1027/2",
    "allowDelivery": false,
    "basePriceDelivery": 500,
    "canceled": false,
    "comments": "Test shipment for documentation",
    "companyId": null,
    "currency": "USD",
    "customPriceDelivery": false,
    "dateAllowDelivery": null,
    "dateCanceled": null,
    "dateDeducted": null,
    "dateInsert": "2026-10-06T11:30:44.000Z",
    "dateMarked": null,
    "dateResponsibleId": "2026-10-06T11:30:44.000Z",
    "deducted": false,
    "deliveryDocDate": null,
    "deliveryDocNum": null,
    "deliveryId": 1,
    "deliveryName": "Courier delivery",
    "deliveryXmlId": null,
    "discountPrice": 0,
    "empAllowDeliveryId": null,
    "empCanceledId": null,
    "empDeductedId": null,
    "empMarkedId": null,
    "empResponsibleId": 1317,
    "externalDelivery": false,
    "id": 1205,
    "id1c": null,
    "marked": false,
    "orderId": 1027,
    "priceDelivery": 500,
    "reasonMarked": null,
    "reasonUndoDeducted": null,
    "responsibleId": 1295,
    "shipmentItems": [],
    "statusId": "DN",
    "statusXmlId": null,
    "system": false,
    "trackingDescription": null,
    "trackingLastCheck": null,
    "trackingNumber": "VIBE-DOC-1",
    "trackingStatus": null,
    "updated1c": false,
    "version1c": null,
    "xmlId": "bx_6ac4cdd46e442"
  }
}

Error response example

422 — no order with this orderId exists:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "Unable to load the order",
    "b24Code": "0"
  }
}

Errors

HTTP Code Description
HTTP400 CodeMISSING_REQUIRED_FIELDS DescriptionThe required field orderId or deliveryId is missing or empty. The field name is in message
HTTP400 CodeREADONLY_FIELD DescriptionThe body contains deducted. The response contains a hint with the ship and unship endpoints
HTTP400 CodeREADONLY_FIELD DescriptionThe body contains another read-only field, such as customPriceDelivery or accountNumber. The field name is in message
HTTP400 CodeINVALID_PARAMS DescriptionA 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
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 rejected the creation. For example, no order with this orderId exists — Unable to load the order
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionThe key's user has no permission to edit orders in Bitrix24
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is in read-only mode
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the sale scope
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens

Full list of common API errors — Errors.

See also