For AI agents: markdown of this page — /docs-content-en/entities/catalog-product-property-enums/create.md documentation index — /llms.txt

Create a list-property value

POST /v1/catalog-product-property-enums

Adds a new option to a product catalog list property. Fields go at the root of the JSON, with no wrapper.

Request fields (body)

Field Type Required Description
FieldpropertyId Typenumber Requiredyes DescriptionIdentifier of the list property. Take it from List properties. The property must have propertyType: "L"
Fieldvalue Typestring Requiredyes DescriptionOption text
FieldxmlId Typestring Requiredyes DescriptionExternal code for imports and integrations
Fieldsort Typenumber Requiredno DescriptionSort order within the property
Fielddef Typeboolean Requiredno DescriptionMake the option the default value of the property
Fieldid Typenumber Requiredno DescriptionRO. The identifier is assigned on creation and must not be sent

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/catalog-product-property-enums" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"propertyId":295,"value":"Additional option","xmlId":"EXTRA-20261013","sort":100,"def":false}'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/catalog-product-property-enums" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"propertyId":295,"value":"Additional option","xmlId":"EXTRA-20261013","sort":100,"def":false}'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/catalog-product-property-enums', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    propertyId: 295,
    value: 'Additional option',
    xmlId: 'EXTRA-20261013',
    sort: 100,
    def: false,
  }),
})

const { data } = await res.json()
console.log(data.id)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/catalog-product-property-enums', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    propertyId: 295,
    value: 'Additional option',
    xmlId: 'EXTRA-20261013',
    sort: 100,
    def: false,
  }),
})

const { data } = await res.json()
console.log(data.id)

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue on a successful request
Fielddata Typeobject DescriptionList-property value
Fielddata.id Typenumber DescriptionIdentifier of the value
Fielddata.propertyId Typenumber DescriptionIdentifier of the owning property
Fielddata.value Typestring DescriptionOption text
Fielddata.def Typeboolean DescriptionWhether the option is the default value of the property
Fielddata.sort Typenumber DescriptionSort order within the property
Fielddata.xmlId Typestring | null DescriptionExternal code. null when the code is not set
Fieldmeta Typeobject DescriptionOptional extra details
Fieldmeta.warnings Typeobject[] DescriptionWarnings about request fields, when there are any
Fieldmeta.warnings[].code Typestring DescriptionWarning code
Fieldmeta.warnings[].message Typestring DescriptionWarning explanation
Fieldmeta.warnings[].field Typestring DescriptionField the warning applies to

Response example

201 — the option is created:

JSON 
{
  "success": true,
  "data": {
    "def": false,
    "id": 1769,
    "propertyId": 295,
    "sort": 100,
    "value": "Additional option",
    "xmlId": "EXTRA-20261013"
  }
}

Error response example

422 — an option with this external code already exists:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "The record with the \"External code\" value equal to \"EXTRA-20261013\" is already in the database",
    "b24Code": "BX_INVALID_VALUE"
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptionInvalid type or shape of a request field
HTTP400 CodeMISSING_REQUIRED_FIELDS DescriptionOne of the required fields was not sent: propertyId, value, xmlId
HTTP400 CodeREADONLY_FIELD DescriptionThe body carries id, which is read-only
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 refusal: a duplicate xmlId, a property of another type, or a property outside the product catalog. The reason is in error.message
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not carry the catalog scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe API key allows reading only
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header was not sent

Full list of common API errors — Errors.

See also