For AI agents: markdown of this page — /docs-content-en/entities/shipments/update.md documentation index — /llms.txt

Update a shipment

PATCH /v1/shipments/:id

Updates an existing shipment of an online store order. Omitted fields are preserved.

Fields are passed flat at the JSON root, without a fields wrapper. How omitted fields are preserved — Shipments.

Parameters

Parameter Type Required Description
Parameterid (path) Typenumber Requiredyes DescriptionShipment ID. List: GET /v1/shipments

Request fields (body)

Field Type Description
FieldtrackingNumber Typestring DescriptionTracking number
FielddeliveryDocNum Typestring DescriptionShipment document number
FielddeliveryDocDate Typedatetime DescriptionShipment document date
FieldallowDelivery Typeboolean DescriptionDelivery is allowed
FieldstatusId Typestring DescriptionDelivery status. List: GET /v1/order-statuses?filter[type]=D
FielddeliveryId Typenumber DescriptionDelivery service ID. List: GET /v1/delivery-services
FieldpriceDelivery Typenumber DescriptionDelivery price
FieldbasePriceDelivery Typenumber DescriptionBase delivery price
FieldresponsibleId Typenumber DescriptionID of the responsible employee. List: GET /v1/users. An empty value, null or 0, is not accepted
FieldcompanyId Typenumber DescriptionCRM company ID. List: GET /v1/companies. 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 /v1/orders/:id
Fieldcomments Typestring DescriptionShipment comment
FieldxmlId Typestring DescriptionExternal code
FieldorderId Typenumber DescriptionRO. Set only on creation
Fielddeducted Typeboolean DescriptionRO. Changed via ship and unship
FieldcustomPriceDelivery Typeboolean DescriptionRO. Manual delivery price flag

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

Examples

curl — personal key

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/shipments/1205" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "trackingNumber": "VIBE-DOC-2",
    "deliveryDocNum": "TN-1205",
    "allowDelivery": true
  }'

curl — OAuth application

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/shipments/1205" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "trackingNumber": "VIBE-DOC-2",
    "deliveryDocNum": "TN-1205",
    "allowDelivery": true
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/shipments/1205', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    trackingNumber: 'VIBE-DOC-2',
    deliveryDocNum: 'TN-1205',
    allowDelivery: true,
  }),
})

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

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/shipments/1205', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    trackingNumber: 'VIBE-DOC-2',
    deliveryDocNum: 'TN-1205',
    allowDelivery: true,
  }),
})

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

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue on success
Fielddata Typeobject DescriptionThe updated shipment with all fields, including omitted ones. All fields — Shipment fields

Response example

JSON 
{
  "success": true,
  "data": {
    "accountNumber": "1027/2",
    "allowDelivery": true,
    "basePriceDelivery": 500,
    "canceled": false,
    "comments": "Test shipment for documentation",
    "companyId": null,
    "currency": "USD",
    "customPriceDelivery": false,
    "dateAllowDelivery": "2026-10-06T11:31:17.000Z",
    "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": "TN-1205",
    "deliveryId": 1,
    "deliveryName": "Courier delivery",
    "deliveryXmlId": null,
    "discountPrice": 0,
    "empAllowDeliveryId": 1317,
    "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-2",
    "trackingStatus": null,
    "updated1c": false,
    "version1c": null,
    "xmlId": "bx_6ac4cdd46e442"
  }
}

Error response example

400 — an empty responsibleId was passed:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Bitrix24 cannot preserve an empty shipment responsibleId and its assignment metadata. Set an explicit nonzero responsibleId or update the shipment in Bitrix24."
  }
}

Errors

HTTP Code Description
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: customPriceDelivery, orderId, accountNumber and others. The field name is in message
HTTP400 CodeEMPTY_UPDATE_BODY DescriptionThe request body is empty
HTTP400 CodeINVALID_PARAMS DescriptionThe body contains no known shipment field — At least one writable shipment field is required.
HTTP400 CodeINVALID_PARAMS DescriptionThe same field is passed twice under different names, such as trackingNumber and TRACKING_NUMBER — Duplicate field alias
HTTP400 CodeINVALID_PARAMS DescriptionThe 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
HTTP400 CodeINVALID_PARAMS DescriptionThe shipment company would be empty after the write, while the order has a different company. Pass a nonzero companyId
HTTP400 CodeINVALID_PARAMS DescriptionThe stored shipment has a manual delivery price (customPriceDelivery is true). Change such a shipment in the Bitrix24 interface
HTTP400 CodeINVALID_PARAMS DescriptionA 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
HTTP400 CodeINVALID_PARAMS Descriptionid in the path is not a non-negative integer
HTTP404 CodeENTITY_NOT_FOUND DescriptionNo shipment with this id exists
HTTP422 CodeBITRIX_NO_EFFECT DescriptionBitrix24 did not return the shipment fields or the order needed to preserve the omitted fields. No write was performed
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 rejected the write or the read of the shipment's order. The reason is in message
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.

Known specifics

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.

Field names are also accepted in upper case. TRACKING_NUMBER is saved the same way as trackingNumber.

See also