Para agentes de IA: markdown desta página — /docs-content-en/entities/catalog-price-types.md índice da documentação — /llms.txt

Os artigos da documentação estão disponíveis atualmente em inglês.

Catalog price types

Price types of your Bitrix24 account: list, retrieve, create, update and delete. A price type is what catalog prices pass in the catalogGroupId field. Bitrix24 requires the Manage price types catalog permission for writes.

Bitrix24 API: catalog.priceType.* Scope: catalog

Create a price type

POST /v1/catalog-price-types

Creates a catalog price type for separate product prices on the Bitrix24 account. The request body is flat, without a fields wrapper.

Request fields (body)

Field Type Required Description
Fieldname Typestring Requiredyes DescriptionPrice type name.
Fieldsort Typenumber Requiredno DescriptionSort order in the Bitrix24 interface.
FieldxmlId Typestring | null Requiredno DescriptionExternal identifier for import and export integrations.
Fieldid Typenumber Requiredno DescriptionRO. Price type ID. List: List price types.
Fieldbase Typestring Requiredno DescriptionRO. Base price type flag, set by the system.
FieldcreatedBy Typenumber | null Requiredno DescriptionRO. ID of the user who created the record. List: List users.
FieldmodifiedBy Typenumber | null Requiredno DescriptionRO. ID of the user who last updated the record. List: List users.
FielddateCreate Typestring | null Requiredno DescriptionRO. Creation date and time in ISO 8601 format.
FieldtimestampX Typestring | null Requiredno DescriptionRO. Last update date and time in ISO 8601 format.

Fields marked RO are read-only. Do not include them in the request body.

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/catalog-price-types" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Wholesale", "sort": 200, "xmlId": "WHOLESALE"}'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/catalog-price-types" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Wholesale", "sort": 200, "xmlId": "WHOLESALE"}'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/catalog-price-types', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"name": "Wholesale", "sort": 200, "xmlId": "WHOLESALE"}),
})

const { success, data } = await res.json()
console.log('ID:', data.id)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/catalog-price-types', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"name": "Wholesale", "sort": 200, "xmlId": "WHOLESALE"}),
})

const { success, data } = await res.json()
console.log('ID:', data.id)

Response fields

The response has status 201 and contains the complete created price type.

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success.
Fielddata Typeobject DescriptionPrice type object.
Fielddata.id Typenumber DescriptionRO. Price type ID. List: List price types. Pass this value in catalogGroupId when working with catalog prices.
Fielddata.name Typestring DescriptionPrice type name.
Fielddata.base Typestring DescriptionRO. Y — the account's base price type, N — another type.
Fielddata.xmlId Typestring | null DescriptionExternal identifier for integrations.
Fielddata.sort Typenumber DescriptionSort order in the Bitrix24 interface.
Fielddata.createdBy Typenumber | null DescriptionRO. ID of the user who created the record. List: List users.
Fielddata.modifiedBy Typenumber | null DescriptionRO. ID of the user who last updated the record. List: List users.
Fielddata.dateCreate Typestring | null DescriptionRO. Creation date and time in ISO 8601 format.
Fielddata.timestampX Typestring | null DescriptionRO. Last update date and time in ISO 8601 format.

Response example

JSON 
{
  "success": true,
  "data": {
    "base": "N",
    "createdBy": 1295,
    "dateCreate": "2026-10-14T17:18:58.000Z",
    "id": 19,
    "modifiedBy": 1295,
    "name": "Wholesale",
    "sort": 200,
    "timestampX": "2026-10-14T17:18:58.000Z",
    "xmlId": "WHOLESALE"
  }
}

Error response example

400 — name was omitted, so the price type was not created:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_REQUIRED_FIELDS",
    "message": "Body field \"name\" is required to create catalogPriceType."
  }
}

Errors

HTTP Code Description
HTTP400 CodeMISSING_REQUIRED_FIELDS Descriptionname was omitted, or its value is null or an empty string.
HTTP400 CodeREADONLY_FIELD DescriptionThe body contains a field marked RO. Remove it from the request.
HTTP400 CodeINVALID_PARAMS DescriptionAn object or array was passed in a string or numeric field.
HTTP400 CodeINVALID_PARAMS DescriptionBitrix24 rejected the request parameters.
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 rejected the request. The reason is in error.message.
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionThe user does not have the Bitrix24 “Manage price types” permission.
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is in read-only mode.
HTTP403 CodeSCOPE_DENIED DescriptionThe key does not have the catalog scope.
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header was omitted.
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no Bitrix24 tokens configured. For an OAuth application key, check the user session.

For the full list of common API errors, see Errors.

Known specifics

On creation, the viewing and buying groups are set to [1, 2] — administrators and all users. This method cannot manage these groups.

See also