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
id (path) number yes Shipment 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
success boolean true on success
data object The shipment with all fields as they are after the mark is set. See Shipment fields
data.deducted boolean Always true in a successful response
data.dateDeducted datetime Date the mark was set
data.empDeductedId number ID 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
400 INVALID_ID The id in the path is not a positive integer. Error message: Shipment ID must be a positive integer.
400 INVALID_PARAMS The request body is not empty or is not an object. Error message: This action takes an empty body.
404 ENTITY_NOT_FOUND No shipment with this id exists. Error message: shipment is not exists
422 BITRIX_NO_EFFECT Bitrix24 did not confirm the mark change. Error message: Bitrix24 did not confirm the shipped mark change.
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.
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.
422 BITRIX_ERROR Bitrix24 rejected the mark. The reason is in message
403 BITRIX_ACCESS_DENIED The key's user has no permission to modify orders in Bitrix24
403 WRITE_BLOCKED_READONLY_KEY The key is in read-only mode
403 SCOPE_DENIED The API key does not have the sale scope
401 MISSING_API_KEY The X-Api-Key header is missing
401 TOKEN_MISSING The 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