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
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/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
Fieldsuccess Typeboolean Descriptiontrue on success
Fielddata Typeobject DescriptionThe shipment with all fields as they are after the mark is cleared. See Shipment fields
Fielddata.deducted Typeboolean DescriptionAlways false in a successful response
Fielddata.dateDeducted Typedatetime DescriptionDate the mark was cleared. The field is not reset
Fielddata.empDeductedId Typenumber DescriptionID of the employee who last changed the mark. The field is not reset. List: GET /v1/users
Fielddata.reasonUndoDeducted Typestring DescriptionStays 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
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 cleared, 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 false. Error message: Bitrix24 did not persist the requested shipped mark.
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 rejected clearing 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

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