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

Shipment fields

GET /v1/shipments/fields

Returns the shipment field schema — a reference for selecting and filtering fields and for the create and update bodies.

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/shipments/fields" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/shipments/fields" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/shipments/fields', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { data } = await res.json()
console.log('Shipment fields:', Object.keys(data.fields))

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/shipments/fields', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { data } = await res.json()

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.fields Typeobject DescriptionField schema. The key is the field name; the value is the field description
Fielddata.fields.<field>.type Typestring DescriptionValue type: number, string, boolean, datetime, array
Fielddata.fields.<field>.readonly Typeboolean Descriptiontrue means the field is set by the system; writing to it is rejected with 400 READONLY_FIELD
Fielddata.fields.<field>.required Typeboolean DescriptionPresent only on fields required at creation, always with the value true
Fielddata.fields.<field>.readonlyOnUpdate Typeboolean DescriptionPresent only on fields that are set at creation and cannot be changed on update, always with the value true
Fielddata.fields.<field>.itemSchema Typeobject DescriptionPresent only on arrays — the schema of an array element
Fielddata.fields.<field>.label Typestring DescriptionShort field name
Fielddata.fields.<field>.description Typestring DescriptionField explanation
Fielddata.aggregatable Typearray DescriptionFields allowed for groupBy grouping in shipment aggregation
Fielddata.batch Typearray DescriptionOperations available in batch calls. For shipments the array is empty

Shipment fields

The full set of fields returned by GET /v1/shipments/fields. The RO column marks read-only fields.

Field Type RO Description
Fieldid Typenumber ROyes DescriptionShipment ID
FieldorderId Typenumber ROno DescriptionOrder ID. List: GET /v1/orders. Required at creation. Set only at creation: on update it is rejected with 400 READONLY_FIELD, marked readonlyOnUpdate in the schema
FieldaccountNumber Typestring ROyes DescriptionShipment number: the order number and the shipment sequence number separated by /, for example 1027/2
FielddeliveryId Typenumber ROno DescriptionDelivery service ID. List: GET /v1/delivery-services. Required at creation
FielddeliveryName Typestring ROyes DescriptionDelivery service name
FielddeliveryXmlId Typestring ROyes DescriptionExternal code of the delivery service. null if not set
FieldstatusId Typestring ROno DescriptionDelivery status. List: GET /v1/order-statuses?filter[type]=D
FieldstatusXmlId Typestring ROyes DescriptionExternal code of the delivery status. null if not set
FieldallowDelivery Typeboolean ROno DescriptionWhether delivery is allowed
FielddateAllowDelivery Typedatetime ROyes DescriptionDate delivery was allowed. null until delivery is allowed
FieldempAllowDeliveryId Typenumber ROyes DescriptionID of the employee who allowed delivery. null until delivery is allowed
Fielddeducted Typeboolean ROyes DescriptionThe "shipped" mark. Set via POST /v1/shipments/:id/ship, cleared via POST /v1/shipments/:id/unship
FielddateDeducted Typedatetime ROyes DescriptionDate the "shipped" mark last changed — when it was set or cleared. null until the mark is first set
FieldempDeductedId Typenumber ROyes DescriptionID of the employee who last changed the "shipped" mark. null until the mark is first set
FieldreasonUndoDeducted Typestring ROyes DescriptionReason the "shipped" mark was cleared. Stays null when the mark is cleared through unship
Fieldcanceled Typeboolean ROyes DescriptionWhether the shipment is canceled
FielddateCanceled Typedatetime ROyes DescriptionCancellation date. null if the shipment is not canceled
FieldempCanceledId Typenumber ROyes DescriptionID of the employee who canceled the shipment. null if the shipment is not canceled
Fieldmarked Typeboolean ROyes DescriptionWhether the shipment is marked as problematic
FielddateMarked Typedatetime ROyes DescriptionDate of the mark. null if there is no mark
FieldempMarkedId Typenumber ROyes DescriptionID of the employee who set the mark. null if there is no mark
FieldreasonMarked Typestring ROyes DescriptionReason for the mark. null if there is no mark
FieldresponsibleId Typenumber ROno DescriptionResponsible employee. List: GET /v1/users
FielddateResponsibleId Typedatetime ROyes DescriptionDate the responsible employee was assigned
FieldempResponsibleId Typenumber ROyes DescriptionID of the employee who assigned the responsible employee
FieldpriceDelivery Typenumber ROno DescriptionDelivery cost
FieldbasePriceDelivery Typenumber ROno DescriptionBase delivery cost
FielddiscountPrice Typenumber ROyes DescriptionDelivery discount
FieldcustomPriceDelivery Typeboolean ROyes DescriptionWhether the delivery cost is set manually
Fieldcurrency Typestring ROyes DescriptionShipment currency, for example USD
FieldcompanyId Typenumber ROno DescriptionCRM company ID from GET /v1/companies. null if no company is set
FielddeliveryDocNum Typestring ROno DescriptionShipment document number. null if not set
FielddeliveryDocDate Typedatetime ROno DescriptionShipment document date. null if not set
FieldtrackingNumber Typestring ROno DescriptionTracking number
FieldtrackingStatus Typestring ROyes DescriptionParcel tracking status. null if there is no tracking
FieldtrackingDescription Typestring ROyes DescriptionTracking status description. null if there is no tracking
FieldtrackingLastCheck Typestring ROyes DescriptionTime of the last tracking status check. null if there was no check
FieldexternalDelivery Typeboolean ROyes DescriptionExternal delivery flag
Fieldsystem Typeboolean ROyes DescriptionSystem shipment of the order. Details — Shipments
Fieldcomments Typestring ROno DescriptionShipment comment
FieldxmlId Typestring ROno DescriptionExternal code of the shipment
Fieldid1c Typestring ROyes DescriptionIdentifier in the ERP system. null if the shipment is not synchronized with an ERP system
Fieldversion1c Typestring ROyes DescriptionVersion in the ERP system. null if the shipment is not synchronized with an ERP system
Fieldupdated1c Typeboolean ROyes DescriptionWhether the shipment was updated through the ERP system
FielddateInsert Typedatetime ROyes DescriptionCreation date
FieldshipmentItems Typearray ROyes DescriptionShipment items. Returned in the GET /v1/shipments/:id response, managed via shipment items

Response example

JSON 
{
  "success": true,
  "data": {
    "fields": {
      "accountNumber": {
        "type": "string",
        "readonly": true,
        "label": "accountNumber",
        "description": "Bitrix24 accountNumber field."
      },
      "allowDelivery": {
        "type": "boolean",
        "readonly": false,
        "label": "Delivery allowed",
        "description": "Delivery allowed."
      },
      "basePriceDelivery": {
        "type": "number",
        "readonly": false,
        "label": "Base delivery price",
        "description": "Base delivery price."
      },
      "canceled": {
        "type": "boolean",
        "readonly": true,
        "label": "canceled",
        "description": "Bitrix24 canceled field."
      },
      "comments": {
        "type": "string",
        "readonly": false,
        "label": "Comment",
        "description": "Comment."
      },
      "companyId": {
        "type": "number",
        "readonly": false,
        "label": "Company ID",
        "description": "Company ID."
      },
      "currency": {
        "type": "string",
        "readonly": true,
        "label": "currency",
        "description": "Bitrix24 currency field."
      },
      "customPriceDelivery": {
        "type": "boolean",
        "readonly": true,
        "label": "Manual delivery price",
        "description": "Manual delivery price."
      },
      "dateAllowDelivery": {
        "type": "datetime",
        "readonly": true,
        "label": "dateAllowDelivery",
        "description": "Bitrix24 dateAllowDelivery field."
      },
      "dateCanceled": {
        "type": "datetime",
        "readonly": true,
        "label": "dateCanceled",
        "description": "Bitrix24 dateCanceled field."
      },
      "dateDeducted": {
        "type": "datetime",
        "readonly": true,
        "label": "dateDeducted",
        "description": "Bitrix24 dateDeducted field."
      },
      "dateInsert": {
        "type": "datetime",
        "readonly": true,
        "label": "Creation date",
        "description": "Creation date."
      },
      "dateMarked": {
        "type": "datetime",
        "readonly": true,
        "label": "dateMarked",
        "description": "Bitrix24 dateMarked field."
      },
      "dateResponsibleId": {
        "type": "datetime",
        "readonly": true,
        "label": "dateResponsibleId",
        "description": "Bitrix24 dateResponsibleId field."
      },
      "deducted": {
        "type": "boolean",
        "readonly": true,
        "label": "Shipped",
        "description": "Shipped mark; use POST /v1/shipments/:id/ship or /unship. Warehouse accounting can deduct stock."
      },
      "deliveryDocDate": {
        "type": "datetime",
        "readonly": false,
        "label": "Delivery document date",
        "description": "Delivery document date."
      },
      "deliveryDocNum": {
        "type": "string",
        "readonly": false,
        "label": "Delivery document number",
        "description": "Delivery document number."
      },
      "deliveryId": {
        "type": "number",
        "readonly": false,
        "required": true,
        "label": "Delivery service ID",
        "description": "Delivery service ID from GET /v1/delivery-services; see /docs/entities/delivery-services."
      },
      "deliveryName": {
        "type": "string",
        "readonly": true,
        "label": "deliveryName",
        "description": "Bitrix24 deliveryName field."
      },
      "deliveryXmlId": {
        "type": "string",
        "readonly": true,
        "label": "deliveryXmlId",
        "description": "Bitrix24 deliveryXmlId field."
      },
      "discountPrice": {
        "type": "number",
        "readonly": true,
        "label": "discountPrice",
        "description": "Bitrix24 discountPrice field."
      },
      "empAllowDeliveryId": {
        "type": "number",
        "readonly": true,
        "label": "empAllowDeliveryId",
        "description": "Bitrix24 empAllowDeliveryId field."
      },
      "empCanceledId": {
        "type": "number",
        "readonly": true,
        "label": "empCanceledId",
        "description": "Bitrix24 empCanceledId field."
      },
      "empDeductedId": {
        "type": "number",
        "readonly": true,
        "label": "empDeductedId",
        "description": "Bitrix24 empDeductedId field."
      },
      "empMarkedId": {
        "type": "number",
        "readonly": true,
        "label": "empMarkedId",
        "description": "Bitrix24 empMarkedId field."
      },
      "empResponsibleId": {
        "type": "number",
        "readonly": true,
        "label": "empResponsibleId",
        "description": "Bitrix24 empResponsibleId field."
      },
      "externalDelivery": {
        "type": "boolean",
        "readonly": true,
        "label": "externalDelivery",
        "description": "Bitrix24 externalDelivery field."
      },
      "id": {
        "type": "number",
        "readonly": true,
        "label": "Shipment ID",
        "description": "Shipment ID."
      },
      "id1c": {
        "type": "string",
        "readonly": true,
        "label": "id1c",
        "description": "Bitrix24 id1c field."
      },
      "marked": {
        "type": "boolean",
        "readonly": true,
        "label": "marked",
        "description": "Bitrix24 marked field."
      },
      "orderId": {
        "type": "number",
        "readonly": false,
        "readonlyOnUpdate": true,
        "required": true,
        "label": "Order ID",
        "description": "Order ID. Lookup: GET /v1/orders."
      },
      "priceDelivery": {
        "type": "number",
        "readonly": false,
        "label": "Delivery price",
        "description": "Delivery price."
      },
      "reasonMarked": {
        "type": "string",
        "readonly": true,
        "label": "reasonMarked",
        "description": "Bitrix24 reasonMarked field."
      },
      "reasonUndoDeducted": {
        "type": "string",
        "readonly": true,
        "label": "reasonUndoDeducted",
        "description": "Bitrix24 reasonUndoDeducted field."
      },
      "responsibleId": {
        "type": "number",
        "readonly": false,
        "label": "Responsible user ID",
        "description": "Responsible user ID."
      },
      "statusId": {
        "type": "string",
        "readonly": false,
        "label": "statusId",
        "description": "Bitrix24 statusId field."
      },
      "statusXmlId": {
        "type": "string",
        "readonly": true,
        "label": "statusXmlId",
        "description": "Bitrix24 statusXmlId field."
      },
      "system": {
        "type": "boolean",
        "readonly": true,
        "label": "System shipment",
        "description": "System shipment."
      },
      "trackingDescription": {
        "type": "string",
        "readonly": true,
        "label": "trackingDescription",
        "description": "Bitrix24 trackingDescription field."
      },
      "trackingLastCheck": {
        "type": "string",
        "readonly": true,
        "label": "trackingLastCheck",
        "description": "Bitrix24 trackingLastCheck field."
      },
      "trackingNumber": {
        "type": "string",
        "readonly": false,
        "label": "Tracking number",
        "description": "Tracking number."
      },
      "trackingStatus": {
        "type": "string",
        "readonly": true,
        "label": "trackingStatus",
        "description": "Bitrix24 trackingStatus field."
      },
      "updated1c": {
        "type": "boolean",
        "readonly": true,
        "label": "updated1c",
        "description": "Bitrix24 updated1c field."
      },
      "version1c": {
        "type": "string",
        "readonly": true,
        "label": "version1c",
        "description": "Bitrix24 version1c field."
      },
      "xmlId": {
        "type": "string",
        "readonly": false,
        "label": "External code",
        "description": "External code."
      },
      "shipmentItems": {
        "type": "array",
        "readonly": true,
        "label": "Shipment positions",
        "description": "Positions returned by get; manage via /v1/shipment-items.",
        "itemSchema": {
          "type": "object"
        }
      }
    },
    "aggregatable": [
      "orderId",
      "priceDelivery",
      "deliveryId"
    ],
    "batch": []
  }
}

Error response example

401 — no API key was provided:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key required. Pass via X-Api-Key header."
  }
}

Errors

HTTP Code Description
HTTP403 CodeSCOPE_DENIED DescriptionThe API key has no sale scope
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens
HTTP429 CodeRATE_LIMITED DescriptionRate limit exceeded: 300 requests per minute per portal. All API keys of the portal share one limit. The current limit is returned in the x-ratelimit-limit header. Retry after the delay in the Retry-After header

For the full list of common API errors, see Errors.

See also