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

Set the "shipped" mark

POST /v1/shipments/:id/ship

Sets the "shipped" mark on an online store order shipment. Call it once the goods are handed over for delivery.

Parameters

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

Pass an empty object {} with the Content-Type: application/json header, or send the request with no body and without this header.

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/shipments/1205/ship" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/shipments/1205/ship" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/shipments/1205/ship', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: '{}',
})

const { success, data } = await res.json()
console.log('Shipped:', data.deducted, '— mark date:', data.dateDeducted)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/shipments/1205/ship', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: '{}',
})

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

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue on success
Fielddata Typeobject DescriptionThe shipment with all fields as they are after the mark is set. See Shipment fields
Fielddata.deducted Typeboolean DescriptionAlways true in a successful response
Fielddata.dateDeducted Typedatetime DescriptionDate the mark was set
Fielddata.empDeductedId Typenumber DescriptionID of the employee who set the mark. List: GET /v1/users

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": "2026-10-06T16:44:20.000Z",
    "dateInsert": "2026-10-06T11:30:44.000Z",
    "dateMarked": null,
    "dateResponsibleId": "2026-10-06T11:30:44.000Z",
    "deducted": true,
    "deliveryDocDate": null,
    "deliveryDocNum": "WB-1205",
    "deliveryId": 1,
    "deliveryName": "Courier delivery",
    "deliveryXmlId": null,
    "discountPrice": 0,
    "empAllowDeliveryId": 1317,
    "empCanceledId": null,
    "empDeductedId": 1317,
    "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-3",
    "trackingStatus": null,
    "updated1c": false,
    "version1c": null,
    "xmlId": "bx_6ac4cdd46e442"
  }
}

Error response example

400 — a field was passed in the request body:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "This action takes an empty body."
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_ID DescriptionThe id in the path is not a positive integer. Error message: Shipment ID must be a positive integer.
HTTP400 CodeINVALID_PARAMS DescriptionThe request body is not empty or is not an object. Error message: This action takes an empty body.
HTTP404 CodeENTITY_NOT_FOUND DescriptionNo shipment with this id exists. Error message: shipment is not exists
HTTP422 CodeBITRIX_NO_EFFECT DescriptionBitrix24 did not confirm the mark change. Error message: Bitrix24 did not confirm the shipped mark change.
HTTP422 CodeBITRIX_NO_EFFECT DescriptionThe mark was set, but the shipment could not be re-read. Error message: Bitrix24 did not return the shipment after the action.
HTTP422 CodeBITRIX_NO_EFFECT DescriptionThe shipment was re-read, but its deducted is not true. Error message: Bitrix24 did not persist the requested shipped mark.
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 rejected the mark. The reason is in message
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionThe key's user has no permission to modify 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

Inventory management. If inventory management is enabled on the Bitrix24 account, the mark may write off stock for the products in the shipment items.

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 /v1/shipments/:id.

A shipment with the mark cannot be deleted. DELETE /v1/shipments/:id returns 422 BITRIX_ERROR while the mark is set. Clear it via POST /v1/shipments/:id/unship before deleting.

See also