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

Item product fields

GET /v1/items/:entityTypeId/:id/products/fields

Returns a description of each field on an item's product rows: name, type, and whether the field is readable and writable.

The discount amount is called discount — matching the data and the write contract. The previous name discountSum remains a deprecated alias: it is still returned by this endpoint and still accepted on write, so code written against the old field list keeps working. Product rows themselves carry only discount — migrate to it.

Parameters

Parameter Type Req. Description
entityTypeId (path) number yes Smart process type ID
id (path) number yes Item ID

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/items/156/741/products/fields" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/items/156/741/products/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/items/156/741/products/fields', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data } = await res.json()
console.log('Fields:', Object.keys(data).length)

JavaScript — OAuth application

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

const { success, data } = await res.json()

Response fields

Field Type RO Req. Description
id integer yes Row ID
productId integer yes Product ID. Catalog: GET /v1/products
productName string Product name
price double Price
quantity double Quantity
discount double Discount amount. Applied when discountTypeId is 1
discountSum double Deprecated alias of discount — accepted on write, absent from product rows
discountRate double Discount percentage. Applied when discountTypeId is 2
discountTypeId integer How the discount is set: 1 — as an amount in discount, 2 — as a percentage in discountRate. Defaults to 2
taxRate double Tax (%)
taxIncluded char Tax included in price (Y/N)
priceExclusive double yes Price excluding tax, with discount
priceNetto double yes Net price
priceBrutto double yes Gross price
measureCode integer Unit of measure code
measureName string yes Unit of measure
customized char yes Modified (Y/N)
sort integer Sort order
type integer yes Type
storeId integer yes Warehouse ID
ownerId integer yes Owner (item) ID
ownerType string yes Owner type
priceAccount double yes Price in the reporting currency
xmlId string yes External code of the row

Response example

The example shows 6 of the 24 fields (23 product-row field names plus the deprecated discountSum alias). Each field is described by the keys type, isRequired, isReadOnly, isImmutable, isMultiple, isDynamic, title. The full list is in the table above.

JSON 
{
  "success": true,
  "data": {
    "id": { "type": "integer", "isRequired": false, "isReadOnly": true, "isImmutable": false, "isMultiple": false, "isDynamic": false, "title": "ID", "description": "Row identity. Read-only as an attribute, and NOT a handle for editing: PUT /products does not preserve it — a row whose fields change comes back with a new id even if the previous one was sent. To edit a row and keep its id use PATCH /products/{rowId}." },
    "ownerId": { "type": "integer", "isRequired": false, "isReadOnly": true, "isImmutable": true, "isMultiple": false, "isDynamic": false, "title": "Owner ID" },
    "ownerType": { "type": "string", "isRequired": false, "isReadOnly": true, "isImmutable": true, "isMultiple": false, "isDynamic": false, "title": "Owner type" },
    "productId": { "type": "integer", "isRequired": true, "isReadOnly": false, "isImmutable": false, "isMultiple": false, "isDynamic": false, "title": "Product" },
    "price": { "type": "double", "isRequired": false, "isReadOnly": false, "isImmutable": false, "isMultiple": false, "isDynamic": false, "title": "Price" },
    "priceExclusive": { "type": "double", "isRequired": false, "isReadOnly": true, "isImmutable": false, "isMultiple": false, "isDynamic": false, "title": "Price excluding tax, with discount" }
  }
}

About id. An id supplied in the items array of PUT /v1/items/:entityTypeId/:id/products does not guarantee that the row keeps its previous identifier: an unchanged row gets the same id even without this field, while a changed row gets a new one. For targeted editing, use PATCH /v1/items/:entityTypeId/:id/products/:rowId.

Error response example

404 — item not found:

JSON 
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Item not found"
  }
}

Errors

HTTP Code Description
400 INVALID_DYNAMIC_PARAM entityTypeId is not a positive integer or is reserved (1, 2, 3, 4, 7, 31)
404 ENTITY_NOT_FOUND Item not found
403 SCOPE_DENIED The API key does not have the crm scope
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