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

Offer fields

GET /v1/catalog-offers/fields

Returns the offer field reference with labels, types, write flags and dictionaries of allowed values, plus the fields available for aggregation and the operations available in a batch request.

With the iblockId parameter, the reference also includes the fields of a specific offer catalog — its propertyNNN properties.

Parameters

Parameter Type Required Description
ParameteriblockId (query) Typenumber Requiredno DescriptionID of the information block backing the offer catalog: catalogs[].iblockId from GET /v1/catalogs, not the catalog record's catalogs[].id; this catalog has productIblockId filled in. With it, the response contains the catalog properties propertyNNN and the service fields negativeAmountTrace, priceType. Without the parameter, with a product catalog's iblockId, or with a nonexistent value, the response carries the base set of 44 fields and the fields_partial warning in meta.warnings

The example's iblockId=27 is the offer catalog's catalogs[].iblockId value. If the catalog record has a different id, use its iblockId.

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/catalog-offers/fields?iblockId=27" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/catalog-offers/fields?iblockId=27" \
  -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/catalog-offers/fields?iblockId=27', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

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

JavaScript — OAuth application

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

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

Response fields

data.fields is an object keyed by field name; each value contains the type, the write flags, a display label and — for fields with a fixed set of values — their dictionary. The set of keys is broken down in the table after the field list. data.aggregatable lists the fields for groupBy in aggregation; numeric functions accept the fields of type number. data.batch lists the operations available in a batch request.

Field Type RO Description
Fieldid Typenumber ROyes DescriptionOffer identifier
Fieldname Typestring ROno DescriptionOffer name. Required on create
Fieldactive Typeboolean ROno DescriptionWhether the offer is active
FieldiblockId Typenumber ROno¹ DescriptionOffer catalog ID. List: GET /v1/catalogs. Required on create, set on create only
FieldparentId Typeobject | null ROno² DescriptionLink to the parent product: value — the parent product ID as a string, valueId — the service ID of the link value, read-only. On create, pass { "value": "<ID>" }. null — a free offer. Parent product IDs: GET /v1/catalog-skus
Fieldtype Typenumber ROyes DescriptionRecord type, computed by Bitrix24: 4 — the offer is linked to a parent product, 5 — a free offer. The filter accepts one exact value
FieldiblockSectionId Typenumber | null ROno DescriptionCatalog section ID. null — the offer is not linked to a section. List: GET /v1/catalog-sections
FieldpurchasingPrice Typenumber | null ROno DescriptionPurchase price. null if not set
FieldpurchasingCurrency Typestring | null ROno DescriptionPurchase price currency, for example USD. null if the purchase price is not set. List: GET /v1/currencies
Fieldquantity Typenumber | null ROno DescriptionStock balance. null if not set
Fieldweight Typenumber | null ROno DescriptionWeight of a product unit. null if not specified
Fieldmeasure Typenumber ROno DescriptionUnit of measure ID. List: GET /v1/catalog-measures
Fieldavailable Typeboolean ROyes DescriptionWhether the offer is available for purchase. Computed by Bitrix24
FieldvatIncluded Typeboolean ROno DescriptionVAT included in the price
Fieldbundle Typeboolean ROyes DescriptionWhether the offer is a bundle. Computed by Bitrix24
FieldcanBuyZero Typeboolean ROno DescriptionAllow purchase when stock is zero
FieldquantityTrace Typeboolean ROno DescriptionQuantity tracking enabled
Fieldsubscribe Typeboolean ROno DescriptionAllow subscription to the product
FieldbarcodeMulti Typeboolean ROno DescriptionAllow separate barcodes for product units
FieldwithoutOrder Typeboolean ROno DescriptionAvailable for ordering without stock on hand
FielddateActiveFrom Typedatetime ROno DescriptionActivity start date. Not accepted in a filter
FielddateActiveTo Typedatetime ROno DescriptionActivity end date. Not accepted in a filter
FieldcreatedBy Typenumber ROyes DescriptionID of the user who created the offer. List: GET /v1/users
FieldmodifiedBy Typenumber ROyes DescriptionID of the user who last modified the offer. List: GET /v1/users
FielddateCreate Typedatetime ROyes DescriptionCreation date. Not accepted in a filter
FieldtimestampX Typedatetime ROyes DescriptionLast modification date. Not accepted in a filter
Fieldcode Typestring | null ROno DescriptionSymbolic code. null if not set
FieldxmlId Typestring ROno DescriptionExternal identifier
Fieldsort Typenumber ROno DescriptionSort order
FieldvatId Typenumber ROno DescriptionVAT rate ID. List: GET /v1/catalog-vat-rates
FieldpreviewText Typestring ROno DescriptionPreview text
FielddetailText Typestring ROno DescriptionDetailed description
FieldpreviewTextType Typestring ROno DescriptionPreview text format: text or html
FielddetailTextType Typestring ROno DescriptionDetailed description format: text or html
FieldpreviewPicture Typeobject ROno DescriptionPreview image
FielddetailPicture Typeobject ROno DescriptionDetail image
FieldiblockSection Typeobject ROno DescriptionArray of catalog section IDs to write on create and update. The primary section is read from iblockSectionId. List: GET /v1/catalog-sections
Fieldwidth Typenumber ROno DescriptionWidth
Fieldheight Typenumber ROno DescriptionHeight
Fieldlength Typenumber ROno DescriptionLength
FieldquantityReserved Typenumber | null ROno DescriptionReserved quantity. null if nothing is reserved
FieldrecurSchemeLength Typenumber ROno DescriptionPayment period length. Available only in on-premise Bitrix24 for content sales
FieldrecurSchemeType Typestring ROno DescriptionPayment period time unit: H — hour, D — day, W — week, M — month, Q — quarter, S — half-year, Y — year. Available only in on-premise Bitrix24 for content sales
FieldtrialPriceId Typenumber ROno DescriptionID of the product used for a trial payment. Available only in on-premise Bitrix24 for content sales
FieldnegativeAmountTrace Typechar ROyes DescriptionCatalog service field. Returned only with iblockId
FieldpriceType Typechar ROno DescriptionCatalog service field. Returned only with iblockId
FieldpropertyNNN Typeproductproperty ROno DescriptionCatalog property, where NNN is the property id from GET /v1/catalog-product-properties. Returned only with iblockId; multiple-value properties come with multiple: true

¹ iblockId is writable on create only — in the reference it comes back with readonly: false and createOnly: true.

² parentId is writable on create only — in the reference it comes back with readonly: false and readonlyOnUpdate: true.

Request headers do not switch the language of labels and descriptions. A field with a fixed set of values — previewTextType and detailTextType — also carries an enum array: every element holds a value to pass in the request and a label for display.

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.fields.<name>.type Typestring DescriptionField type: number, string, boolean, datetime, object. Catalog fields use char and productproperty
Fielddata.fields.<name>.label Typestring DescriptionShort field label. For catalog fields the label matches the field name
Fielddata.fields.<name>.description Typestring DescriptionExtended field description: what it is for, where to get the list of allowed values, write-time behavior. The key is present on fields that have something to add to the label
Fielddata.fields.<name>.readonly Typeboolean Descriptiontrue — the field is filled by the system and is not accepted on create or update
Fielddata.fields.<name>.required Typeboolean Descriptiontrue — the field is required on create. Present on name and iblockId
Fielddata.fields.<name>.createOnly Typeboolean Descriptiontrue — the field is accepted on create only; on PATCH it is rejected with READONLY_FIELD. Present on iblockId
Fielddata.fields.<name>.readonlyOnUpdate Typeboolean Descriptiontrue — the field is accepted on create; on PATCH it is rejected with READONLY_FIELD. Present on parentId
Fielddata.fields.<name>.properties Typeobject DescriptionNested keys of an object field with their types. On parentId — value and valueId, the latter with readonly: true
Fielddata.fields.<name>.writeOnly Typeboolean Descriptiontrue — the field is accepted on write and is not returned in responses. Present on iblockSection
Fielddata.fields.<name>.notReturned Typeboolean Descriptiontrue — the field name is not supported in select: a list request with it returns an UNKNOWN_SELECT_FIELD warning. Present on iblockSection
Fielddata.fields.<name>.nullable Typeboolean Descriptiontrue — the field can come back as null. The key is present only on such fields
Fielddata.fields.<name>.multiple Typeboolean Descriptiontrue — the catalog property accepts several values. The key is present only on such properties
Fielddata.aggregatable Typestring[] DescriptionFields for groupBy in aggregation: purchasingPrice, quantity, iblockSectionId
Fielddata.batch Typestring[] DescriptionOffer operations available in a batch request: create, update, delete
Fieldmeta.warnings Typearray DescriptionWarnings. An element with code: fields_partial arrives when the response is built without catalog fields — without iblockId, or with an iblockId that does not belong to an offer catalog

Response example

JSON 
{
  "success": true,
  "data": {
    "fields": {
      "id": {
        "type": "number",
        "readonly": true,
        "label": "Product identifier",
        "description": "Unique identifier of the catalog product."
      },
      "iblockId": {
        "type": "number",
        "readonly": false,
        "createOnly": true,
        "required": true,
        "label": "Catalog ID",
        "description": "Catalog the product belongs to. Available values: GET /v1/catalogs. Set on create only — changing it via PATCH is rejected, a product cannot be moved between catalogs."
      },
      "parentId": {
        "type": "object",
        "readonly": false,
        "readonlyOnUpdate": true,
        "nullable": true,
        "label": "Parent product ID",
        "description": "Link to a catalog SKU or product. On create pass {\"value\":\"<parent id>\"}; omit for a free offer. Bitrix24 returns value and valueId. Updates to this field are rejected because Bitrix24 silently ignores them.",
        "properties": {
          "value": { "type": "string" },
          "valueId": { "type": "string", "readonly": true }
        }
      },
      "type": {
        "type": "number",
        "readonly": true,
        "label": "Bitrix24 product type",
        "description": "Computed by Bitrix24. A free offer has a different type from an offer linked to a parent. Filtering accepts only exact type 4 or 5."
      },
      "iblockSection": {
        "type": "object",
        "readonly": false,
        "writeOnly": true,
        "notReturned": true,
        "label": "Catalog sections",
        "description": "Array of catalog section IDs the product belongs to. Accepted on create and update only — on read the primary section arrives as the scalar iblockSectionId. Available values: GET /v1/catalog-sections."
      },
      "previewTextType": {
        "type": "string",
        "readonly": false,
        "label": "Preview text format",
        "description": "Format of previewText.",
        "enum": [
          { "value": "text", "label": "Plain text" },
          { "value": "html", "label": "HTML" }
        ]
      },
      "property909": {
        "type": "productproperty",
        "readonly": false,
        "multiple": true,
        "label": "property909"
      }
    },
    "aggregatable": [
      "purchasingPrice",
      "quantity",
      "iblockSectionId"
    ],
    "batch": [
      "create",
      "update",
      "delete"
    ]
  }
}

The example is trimmed to seven fields — one each for readonly, createOnly with required, readonlyOnUpdate with properties, the computed type, the writeOnly + notReturned pair, an enum dictionary and a multiple-value catalog property. With iblockId=27, the test Bitrix24 account returns 55 fields.

Without iblockId, the response contains a warning:

JSON 
{
  "success": true,
  "data": { "fields": { /* 44 fields */ }, "aggregatable": [ /* ... */ ], "batch": [ /* ... */ ] },
  "meta": {
    "warnings": [
      {
        "code": "fields_partial",
        "message": "Dynamic field metadata from Bitrix24 was unavailable; the response carries static schema fields only and some labels may be missing. Retry to obtain the complete set."
      }
    ]
  }
}

Error response example

401 — the key was not passed:

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 does not have the catalog scope
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header was not passed
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.

Known specifics

A retry does not clear fields_partial without iblockId. The warning suggests retrying the request, but without the offer catalog's iblockId a retry returns the same base set. The forty-four base fields in this response are complete; only the catalog properties and service fields are missing — a request with ?iblockId= returns them.

Some fields are not returned in the list by default. The symbolic code code, the external code xmlId, the sort order sort, the VAT rate vatId, the dimensions width, height, length, the texts, the pictures, quantityReserved, recurSchemeLength, recurSchemeType, trialPriceId and the propertyNNN properties are not returned in the GET /v1/catalog-offers response without an explicit ?select=. List the names you need in select to get them in the list. The single-offer response, GET /v1/catalog-offers/:id, always returns them.

Labels call the record a product. In the reference's label and description, an offer is called a product — the labels match Catalog product fields. The type and parentId fields exist only on offers.

See also