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
success boolean Always true on success
data.fields object Field schema. The key is the field name, the value is the field description
data.fields.<field>.type string Value type: number, string, boolean, datetime, array
data.fields.<field>.readonly boolean true means the field is set by the system; writing to it is rejected with 400 READONLY_FIELD
data.fields.<field>.required boolean Present only on fields required at creation, always with the value true
data.fields.<field>.readonlyOnUpdate boolean Present only on fields that are set at creation and cannot be changed on update, always with the value true
data.fields.<field>.itemSchema object Present only on arrays — the schema of an array element
data.fields.<field>.label string Short field name
data.fields.<field>.description string Field explanation
data.aggregatable array Fields allowed for groupBy grouping in shipment aggregation
data.batch array Operations 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
id number yes Shipment ID
orderId number no Order 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
accountNumber string yes Shipment number: the order number and the shipment sequence number separated by /, for example 1027/2
deliveryId number no Delivery service ID. List: GET /v1/delivery-services. Required at creation
deliveryName string yes Delivery service name
deliveryXmlId string yes External code of the delivery service. null if not set
statusId string no Delivery status. List: GET /v1/order-statuses?filter[type]=D
statusXmlId string yes External code of the delivery status. null if not set
allowDelivery boolean no Whether delivery is allowed
dateAllowDelivery datetime yes Date delivery was allowed. null until delivery is allowed
empAllowDeliveryId number yes ID of the employee who allowed delivery. null until delivery is allowed
deducted boolean yes The "shipped" mark. Set via POST /v1/shipments/:id/ship, cleared via POST /v1/shipments/:id/unship
dateDeducted datetime yes Date the "shipped" mark last changed — when it was set or cleared. null until the mark is first set
empDeductedId number yes ID of the employee who last changed the "shipped" mark. null until the mark is first set
reasonUndoDeducted string yes Reason the "shipped" mark was cleared. Stays null when the mark is cleared through unship
canceled boolean yes Whether the shipment is canceled
dateCanceled datetime yes Cancellation date. null if the shipment is not canceled
empCanceledId number yes ID of the employee who canceled the shipment. null if the shipment is not canceled
marked boolean yes Whether the shipment is marked as problematic
dateMarked datetime yes Date of the mark. null if there is no mark
empMarkedId number yes ID of the employee who set the mark. null if there is no mark
reasonMarked string yes Reason for the mark. null if there is no mark
responsibleId number no Responsible employee. List: GET /v1/users
dateResponsibleId datetime yes Date the responsible employee was assigned
empResponsibleId number yes ID of the employee who assigned the responsible employee
priceDelivery number no Delivery cost
basePriceDelivery number no Base delivery cost
discountPrice number yes Delivery discount
customPriceDelivery boolean yes Whether the delivery cost is set manually
currency string yes Shipment currency, for example USD
companyId number no CRM company ID from GET /v1/companies. null if no company is set
deliveryDocNum string no Shipment document number. null if not set
deliveryDocDate datetime no Shipment document date. null if not set
trackingNumber string no Tracking number
trackingStatus string yes Parcel tracking status. null if there is no tracking
trackingDescription string yes Tracking status description. null if there is no tracking
trackingLastCheck string yes Time of the last tracking status check. null if there was no check
externalDelivery boolean yes External delivery flag
system boolean yes System shipment of the order. Details — Shipments
comments string no Shipment comment
xmlId string no External code of the shipment
id1c string yes Identifier in the ERP system. null if the shipment is not synchronized with an ERP system
version1c string yes Version in the ERP system. null if the shipment is not synchronized with an ERP system
updated1c boolean yes Whether the shipment was updated through the ERP system
dateInsert datetime yes Creation date
shipmentItems array yes Shipment 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 — the API key is not passed:

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

Errors

HTTP Code Description
403 SCOPE_DENIED The API key has no sale scope
401 MISSING_API_KEY The X-Api-Key header is not passed
401 TOKEN_MISSING The API key has no configured tokens
429 RATE_LIMITED Rate limit exceeded: 300 requests per minute per portal, all API keys of the portal share one limit. The exact value arrives in the x-ratelimit-limit header (the cap is divided across replicas). Retry after the delay in the Retry-After header

Full list of common API errors — Errors.

See also