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

SKU fields

GET /v1/catalog-skus/fields

Returns the parent product field reference with labels, types, read and write availability flags, descriptions and enum dictionaries where the value set is fixed, the list of fields for grouping in aggregation, and the operations available in a batch request.

The dateCreate, timestampX, dateActiveFrom, and dateActiveTo fields are not accepted in filter: the request returns 400 UNKNOWN_FILTER_FIELD before calling Bitrix24. These dates remain available in select and responses.

Parameters

Parameter Type Required Description
ParameteriblockId (query) Typenumber Requiredno DescriptionID of the information block backing the product catalog: catalogs[].iblockId from GET /v1/catalogs, not the catalog record's catalogs[].id. With it, the reference is extended with the catalog properties propertyNNN and the priceType field. Without it, and also with the iblockId of an offer catalog or of a nonexistent catalog, the response has 24 static fields and the fields_partial warning in meta.warnings

In the examples, iblockId=25 is the product 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-skus/fields?iblockId=25" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/catalog-skus/fields?iblockId=25" \
  -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-skus/fields?iblockId=25', {
  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-skus/fields?iblockId=25', {
  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 whose key matches the field name, and whose value contains the type, the write-access 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. data.batch lists the operations available in a batch request.

Field Type RO Description
Fieldid Typenumber ROyes DescriptionParent product identifier
Fieldname Typestring ROno DescriptionParent product name. Required on create
Fieldactive Typeboolean ROno DescriptionWhether the product is active
FieldiblockId Typenumber ROno¹ DescriptionProduct catalog ID. List: GET /v1/catalogs. Required on create, set on create only
FieldiblockSectionId Typenumber | null ROno DescriptionPrimary catalog section ID. null — the product is not linked to a section. List: GET /v1/catalog-sections
Fieldavailable Typeboolean ROyes DescriptionWhether the product is available for purchase. Computed by Bitrix24
Fieldbundle Typeboolean ROyes DescriptionWhether the product is a bundle. Computed by Bitrix24
FielddateActiveFrom Typedatetime ROno DescriptionActivity start date. Not accepted in filters (400 UNKNOWN_FILTER_FIELD)
FielddateActiveTo Typedatetime ROno DescriptionActivity end date. Not accepted in filters (400 UNKNOWN_FILTER_FIELD)
FieldcreatedBy Typenumber ROyes DescriptionID of the user who created the product. List: GET /v1/users
FieldmodifiedBy Typenumber ROyes DescriptionID of the user who last modified the product. List: GET /v1/users
FielddateCreate Typedatetime ROyes DescriptionCreation date. Not accepted in filters (400 UNKNOWN_FILTER_FIELD)
FieldtimestampX Typedatetime ROyes DescriptionLast modification date. Not accepted in filters (400 UNKNOWN_FILTER_FIELD)
Fieldcode Typestring | null ROno DescriptionProduct symbolic code. null if not set
FieldxmlId Typestring ROno DescriptionExternal code
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
Fieldsort Typenumber ROno DescriptionSort order
FieldpreviewPicture Typeobject | null ROno DescriptionPreview image. Returned as an object { id, url, urlMachine } or null. The field cannot be used for filtering or sorting
FielddetailPicture Typeobject | null ROno DescriptionDetail image, same format. The field cannot be used for filtering or sorting
FieldiblockSection Typearray | null ROno DescriptionArray of IDs of all product sections. Accepted on create and update. In the get, create and update responses it arrives as an array or null. It is not returned by the list and search endpoints and is not supported in select — the name triggers the UNKNOWN_SELECT_FIELD warning. List: GET /v1/catalog-sections
Fieldtype Typenumber ROyes DescriptionProduct type, computed by Bitrix24: 6 — a parent product without offers, 3 — with offers. The filter accepts one exact number, 3 or 6

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

With the iblockId of a product catalog, data.fields gains the priceType field of type char and the catalog properties propertyNNN of type productproperty. Property names and types are returned by GET /v1/catalog-product-properties.

Request headers do not switch the language of labels and descriptions. Enum values carry an English label.

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.fields.<name>.type Typestring DescriptionField type: number, string, boolean, datetime, object, array. For the priceType field — char, for catalog properties — productproperty
Fielddata.fields.<name>.label Typestring DescriptionField label. For static fields — in English, for priceType and catalog properties it 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
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 (name, iblockId). The key is present only on such fields
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>.writeOnly Typeboolean Descriptiontrue — the field is accepted on write and is not returned by the list and search endpoints (present on iblockSection)
Fielddata.fields.<name>.notReturned Typeboolean Descriptiontrue — the name is not supported in select (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 stores several values and arrives as an array. The key is present only on such properties
Fielddata.fields.<name>.itemSchema Typeobject DescriptionSchema of an array element. The key is present on iblockSection: { "type": "number" }, the elements are numeric section IDs
Fielddata.fields.<name>.enum Typearray DescriptionDictionary of allowed values: an array of { value, label }. The key is present on previewTextType and detailTextType. Send value — label is meant for display
Fielddata.aggregatable Typestring[] DescriptionFields for groupBy in aggregation: iblockSectionId
Fielddata.batch Typestring[] DescriptionParent product operations available in a batch request: create, update, delete
Fieldmeta.warnings Typearray DescriptionReturned when the request has no product catalog iblockId: an element { code: "fields_partial", message } — the response has only the static fields

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."
      },
      "code": {
        "type": "string",
        "readonly": false,
        "nullable": true,
        "label": "Symbolic code",
        "description": "Symbolic product code; null when not set."
      },
      "iblockSection": {
        "type": "array",
        "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.",
        "itemSchema": { "type": "number" }
      },
      "previewTextType": {
        "type": "string",
        "readonly": false,
        "label": "Preview text format",
        "description": "Format of previewText.",
        "enum": [
          { "value": "text", "label": "Plain text" },
          { "value": "html", "label": "HTML" }
        ]
      },
      "type": {
        "type": "number",
        "readonly": true,
        "label": "Bitrix24 product type",
        "description": "Computed by Bitrix24. A newly created SKU starts as an empty SKU and changes type when offers are linked. Filtering accepts only exact type 3 or 6."
      },
      "property293": {
        "type": "productproperty",
        "readonly": false,
        "multiple": true,
        "label": "property293"
      }
    },
    "aggregatable": [
      "iblockSectionId"
    ],
    "batch": [
      "create",
      "update",
      "delete"
    ]
  }
}

The example is trimmed to seven fields — one each for the readonly flag, createOnly with required, nullable, the writeOnly + notReturned pair with the itemSchema element schema, the enum dictionary, the computed type, and a catalog property with multiple. The response returns all 24 static fields, and with the iblockId of a product catalog — also priceType and all catalog properties.

Error response example

403 — the key does not have the catalog scope:

JSON 
{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'catalog' scope",
    "hint": "This request needs the 'catalog' scope, which the calling key does not carry. Add 'catalog' to this key in the developer cabinet (or through the management API), then repeat the call.",
    "cause": "key_scope_missing",
    "requiredScope": "catalog",
    "keyScopes": ["task", "im"],
    "fix": { "action": "edit_key_scopes", "via": "cabinet" },
    "userMessage": "The app's API key lacks the “Product catalog” permission. You can add it in the key settings in the developer cabinet."
  }
}

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

Some fields are not returned in the list by default. The symbolic code code, the external code xmlId, the sort order sort, the texts previewText and detailText with their formats, and the images are not returned in the GET /v1/catalog-skus response without an explicit select. List the names you need in select to get them in the list. In the single-product response GET /v1/catalog-skus/:id they are always returned.

See also