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

Clear the "shipped" mark

POST /v1/shipments/:id/unship

Clears the "shipped" mark from an online store order shipment, for example before deleting the shipment or after setting the mark by mistake.

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/unship" \
  -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/unship" \
  -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/unship', {
  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)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/shipments/1205/unship', {
  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 cleared. See Shipment fields
data.deducted boolean Always false in a successful response
data.dateDeducted datetime Date the mark was cleared. The field is not reset
data.empDeductedId number ID of the employee who last changed the mark. The field is not reset. List: GET /v1/users
data.reasonUndoDeducted string Stays null: the method does not accept a reason for clearing the mark

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:45:13.000Z",
    "dateInsert": "2026-10-06T11:30:44.000Z",
    "dateMarked": null,
    "dateResponsibleId": "2026-10-06T11:30:44.000Z",
    "deducted": false,
    "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

404 — shipment not found:

JSON 
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "shipment is not exists"
  }
}

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 cleared, 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 false. Error message: Bitrix24 did not persist the requested shipped mark.
422 BITRIX_ERROR Bitrix24 rejected clearing 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

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

See also