Add Parent Product v 3.0 catalog.product.sku.add
Choose a tool for developing with an AI agent:
- use Alaio Vibecode to build an app for Bitrix24 from a task description without knowing any programming language. The agent writes the code and deploys the app to a server, with no manual hosting setup
- use the MCP server to develop a REST API integration in your own project. The agent refers to the official REST documentation
Scope:
catalogWho can execute the method: a user with the "Create product" access permission and one of the following permissions: "View product catalog", "View catalog products", or "Edit selling price"
The method belongs to REST 3.0. The call specifics and response format of the new API version are described in the REST 3.0 overview.
The method catalog.product.sku.add creates a parent product in the product catalog and returns its fields.
Method Parameters
Required parameters are marked with *
|
Name |
Description |
|
fields* |
Object with the fields of the new parent product. Field description |
Parameter fields
Required parameters are marked with *
|
Name |
Description |
|
iblockId* |
Identifier of the product catalog information block. The identifier can be retrieved using the catalog.catalog.list method: it is the catalog whose |
|
name* |
Parent product name |
|
code |
Symbolic code |
|
xmlId |
External code. If not passed on creation, it matches |
|
active |
Activity. Possible values:
Any value other than Default: |
|
sort |
Sort index. Default: |
|
createdBy |
Identifier of the user who created the record. The identifier can be retrieved using the user.get method |
|
modifiedBy |
Identifier of the user who modified the record. Defaults to the current user |
|
dateActiveFrom |
Activity start date in ISO 8601 format |
|
dateActiveTo |
Activity end date in ISO 8601 format |
|
previewText |
Preview description |
|
previewTextType |
Preview description type. Possible values:
Default: |
|
previewPicture |
Preview picture. The method does not currently save the field value, see the warning below for details |
|
detailText |
Detailed description |
|
detailTextType |
Detailed description type. Possible values:
Default: |
|
detailPicture |
Detail picture. The method does not currently save the field value, see the warning below for details |
|
iblockSectionId |
Identifier of the main section. The identifier can be retrieved using the catalog.section.list method. For a non-existent section, the method returns an access error |
|
iblockSection |
Array of identifiers of all sections to link the product to |
|
quantity |
Available quantity. The value is not saved when inventory management is enabled |
|
quantityReserved |
Reserved quantity |
|
quantityTrace |
Quantity tracking. Possible values:
Always |
|
canBuyZero |
Allow purchase when the product is out of stock. Possible values:
The value is not saved for a parent product |
|
subscribe |
Allow subscription to the product. Possible values:
|
|
vatId |
VAT rate identifier. The identifier can be retrieved using the catalog.vat.list method |
|
vatIncluded |
Whether VAT is included in the price. Possible values:
|
|
purchasingPrice |
Purchase price. The value is not saved when inventory management is enabled |
|
purchasingCurrency |
Purchase price currency, for example |
|
barcodeMulti |
Unique barcodes for each item. Possible values:
|
|
weight |
Weight |
|
length |
Length |
|
width |
Width |
|
height |
Height |
|
measure |
Unit of measurement identifier. The identifier can be retrieved using the catalog.measure.list method |
|
recurSchemeLength |
Payment period length. Used only in the on-premise version for content sales |
|
recurSchemeType |
Time unit of the payment period. Used only in the on-premise version for content sales |
|
trialPriceId |
Product for trial payment. Used only in the on-premise version for content sales |
|
withoutOrder |
Renewal without placing an order: |
|
quantityTraceRaw |
Quantity tracking, taking the default value into account. Possible values:
|
|
paymentType |
Payment type. Possible values:
Used only in the on-premise version for content sales |
|
subscribeRaw |
Subscription to the product, taking the default value into account. Possible values:
|
|
canBuyZeroRaw |
Purchase when out of stock, taking the default value into account. Possible values:
|
|
properties |
Product property values. The key is Keys of any other form cause a validation error. One property cannot be passed under two keys, for example |
The id, type, available, bundle, dateCreate, and timestampX fields are filled in automatically. If you pass id or type in fields, the method returns an error.
The method accepts the previewPicture and detailPicture fields in the {"fileData": ["file_name", "base64_content"]} and {"remove": "Y"} formats, but does not currently save them: the picture is neither added nor removed, and no error occurs. Add product images using the catalog.product.image.add method.
Code Examples
How to Use Examples in Documentation
The new API call differs by adding the /api/ segment to the request URL:
https://{installation_address}/rest/api/{user_id}/{webhook_token}/catalog.product.sku.add
curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"fields":{"iblockId":25,"name":"DOCS-V3-SKU T-shirt","code":"docs-v3-sku-t-shirt","iblockSectionId":31,"previewText":"Cotton T-shirt","sort":100}}' \
https://**put_your_bitrix24_address**/rest/api/**put_your_user_id_here**/**put_your_webhook_here**/catalog.product.sku.add
curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"fields":{"iblockId":25,"name":"DOCS-V3-SKU T-shirt","code":"docs-v3-sku-t-shirt","iblockSectionId":31,"previewText":"Cotton T-shirt","sort":100},"auth":"**put_access_token_here**"}' \
https://**put_your_bitrix24_address**/rest/api/catalog.product.sku.add
import { Text } from '@bitrix24/b24jssdk'
import type { B24Frame } from '@bitrix24/b24jssdk'
declare const $b24: B24Frame
type SkuAddResult = {
item: {
id: number
iblockId: number
name: string
type: number
properties: Record<string, unknown>
}
}
try {
const response = await $b24.actions.v3.call.make<SkuAddResult>({
method: 'catalog.product.sku.add',
params: {
fields: {
iblockId: 25,
name: 'DOCS-V3-SKU T-shirt',
code: 'docs-v3-sku-t-shirt',
iblockSectionId: 31,
previewText: 'Cotton T-shirt',
sort: 100,
},
},
requestId: Text.getUuidRfc4122()
})
if (!response.isSuccess) {
console.error(response.getErrorMessages().join('; '))
} else {
const result = response.getData()!.result
console.info('Created:', result.item.id, result.item.type)
}
} catch (error) {
// Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
console.error(error)
}
<script src="https://unpkg.com/@bitrix24/b24jssdk@1/dist/umd/index.min.js"></script>
<script>
async function addSku() {
try {
const $b24 = await B24Js.initializeB24Frame()
const response = await $b24.actions.v3.call.make({
method: 'catalog.product.sku.add',
params: {
fields: {
iblockId: 25,
name: 'DOCS-V3-SKU T-shirt',
code: 'docs-v3-sku-t-shirt',
iblockSectionId: 31,
previewText: 'Cotton T-shirt',
sort: 100,
},
},
requestId: B24Js.Text.getUuidRfc4122()
})
if (!response.isSuccess) {
console.error(response.getErrorMessages().join('; '))
return
}
const result = response.getData().result
console.info('Created:', result.item.id, result.item.type)
} catch (error) {
// Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
console.error(error)
}
}
document.addEventListener('DOMContentLoaded', addSku)
</script>
from b24pysdk.errors import BitrixAPIError, BitrixSDKException
try:
bitrix_response = client.catalog.product.sku.add(
fields={
"iblockId": 25,
"name": "DOCS-V3-SKU T-shirt",
"code": "docs-v3-sku-t-shirt",
"iblockSectionId": 31,
"previewText": "Cotton T-shirt",
"sort": 100,
},
).response
result = bitrix_response.result
print(result)
except BitrixAPIError as error:
print(
"Bitrix API error",
f"error: {error.error}",
f"error_description: {error.error_description}",
sep="\n",
)
except BitrixSDKException as error:
print(f"Bitrix SDK error: {error.message}")
except Exception as error:
print(f"Unexpected error: {error}")
SDKs do not yet support the /rest/api/ address in calls. Use direct HTTP requests, for example, via cURL or fetch.
try {
$response = $b24Service
->core
->call(
'catalog.product.sku.add',
[
'fields' => [
'iblockId' => 25,
'name' => 'DOCS-V3-SKU T-shirt',
'code' => 'docs-v3-sku-t-shirt',
'iblockSectionId' => 31,
'previewText' => 'Cotton T-shirt',
'sort' => 100,
],
]
);
$result = $response
->getResponseData()
->getResult();
if ($result->error()) {
error_log($result->error());
} else {
echo 'Success: ' . print_r($result->data(), true);
}
} catch (Throwable $e) {
error_log($e->getMessage());
echo 'Error: ' . $e->getMessage();
}
SDKs do not yet support the /rest/api/ address in calls. Use direct HTTP requests, for example, via cURL or fetch.
BX24.callMethod(
'catalog.product.sku.add',
{
fields: {
iblockId: 25,
name: 'DOCS-V3-SKU T-shirt',
code: 'docs-v3-sku-t-shirt',
iblockSectionId: 31,
previewText: 'Cotton T-shirt',
sort: 100,
},
},
result => {
if (result.error())
console.error(result.error());
else
console.dir(result.data());
}
);
SDKs do not yet support the /rest/api/ address in calls. Use direct HTTP requests, for example, via cURL or fetch.
require_once('crest.php');
$result = CRest::call(
'catalog.product.sku.add',
[
'fields' => [
'iblockId' => 25,
'name' => 'DOCS-V3-SKU T-shirt',
'code' => 'docs-v3-sku-t-shirt',
'iblockSectionId' => 31,
'previewText' => 'Cotton T-shirt',
'sort' => 100,
],
]
);
echo '<PRE>';
print_r($result);
echo '</PRE>';
// client and ctx are already created — see the Go SDK section
res, err := client.Core().Call(ctx, "catalog.product.sku.add", b24.Params{
"fields": b24.Params{
"iblockId": 25,
"name": "DOCS-V3-SKU T-shirt",
"code": "docs-v3-sku-t-shirt",
"iblockSectionId": 31,
"previewText": "Cotton T-shirt",
"sort": 100,
},
})
if err != nil {
return fmt.Errorf("catalog.product.sku.add: %w", err)
}
// The method wraps the response in an object with the "item" key.
raw, ok := b24.Unwrap(res.Result, "item")
if !ok {
return fmt.Errorf("the response has no item key")
}
var item struct {
ID int `json:"id"`
Name string `json:"name"`
Type int `json:"type"`
}
if err := json.Unmarshal(raw, &item); err != nil {
return fmt.Errorf("parsing the response: %w", err)
}
fmt.Println(item.ID, item.Name, item.Type)
Response Handling
HTTP status: 200
{
"result": {
"item": {
"id": 7553,
"iblockId": 25,
"name": "DOCS-V3-SKU T-shirt",
"code": "docs-v3-sku-t-shirt",
"xmlId": "7553",
"active": "Y",
"sort": 100,
"createdBy": 1,
"modifiedBy": 1,
"dateCreate": "2026-10-22T12:18:48+02:00",
"timestampX": "2026-10-22T12:18:48+02:00",
"dateActiveFrom": null,
"dateActiveTo": null,
"previewText": "Cotton T-shirt",
"previewTextType": "text",
"previewPicture": null,
"detailText": null,
"detailTextType": "text",
"detailPicture": null,
"iblockSectionId": 31,
"iblockSection": [
31
],
"type": 6,
"available": "N",
"bundle": "N",
"quantity": 0,
"quantityReserved": 0,
"quantityTrace": "Y",
"canBuyZero": "N",
"subscribe": "Y",
"vatId": null,
"vatIncluded": "N",
"purchasingPrice": null,
"purchasingCurrency": null,
"barcodeMulti": "N",
"weight": 0,
"length": null,
"width": null,
"height": null,
"measure": null,
"recurSchemeLength": null,
"recurSchemeType": "D",
"trialPriceId": null,
"withoutOrder": "N",
"quantityTraceRaw": "Y",
"paymentType": "S",
"subscribeRaw": "D",
"canBuyZeroRaw": "N",
"properties": {
"PROPERTY_309": null,
"PROPERTY_293": null,
"PROPERTY_295": null,
"PROPERTY_297": null,
"PROPERTY_299": null,
"PROPERTY_301": null,
"PROPERTY_303": null,
"PROPERTY_305": null,
"PROPERTY_307": null,
"PROPERTY_311": null,
"PROPERTY_313": null,
"PROPERTY_315": null,
"PROPERTY_329": null,
"PROPERTY_343": null,
"PROPERTY_359": null,
"PROPERTY_431": null,
"PROPERTY_433": null,
"PROPERTY_435": null,
"PROPERTY_893": null,
"PROPERTY_897": null,
"PROPERTY_901": null,
"PROPERTY_917": null,
"PROPERTY_921": null,
"PROPERTY_931": null,
"PROPERTY_933": null,
"PROPERTY_935": null,
"PROPERTY_1013": null,
"PROPERTY_1015": null,
"PROPERTY_1019": null,
"PROPERTY_1021": null,
"PROPERTY_1023": null,
"PROPERTY_1077": null,
"PROPERTY_1079": null,
"PROPERTY_1081": null,
"PROPERTY_1083": null,
"PROPERTY_1085": null,
"PROPERTY_1231": null
}
}
},
"time": {
"start": 1792660728,
"finish": 1792660728.590604,
"duration": 0.5906040668487549,
"processing": 0,
"date_start": "2026-10-22T12:18:48+02:00",
"date_finish": "2026-10-22T12:18:48+02:00",
"operating_reset_at": 1792660920,
"operating": 0.38518595695495605
}
}
Returned Data
|
Name |
Description |
|
result |
Object with the response data |
|
result.item |
Fields of the created parent product. Field description |
|
time |
Information about the request execution time |
Item Object
|
Name |
Description |
|
id |
Parent product identifier |
|
iblockId |
Identifier of the product catalog information block |
|
name |
Parent product name |
|
code |
Symbolic code |
|
xmlId |
External code. If not set, it matches |
|
active |
Activity: |
|
sort |
Sort index |
|
createdBy |
Identifier of the user who created the record |
|
modifiedBy |
Identifier of the user who last modified the record |
|
dateCreate |
Creation date and time |
|
timestampX |
Date and time of the last modification |
|
dateActiveFrom |
Activity start date |
|
dateActiveTo |
Activity end date |
|
previewText |
Preview description |
|
previewTextType |
Preview description type: |
|
previewPicture |
Preview picture file identifier |
|
detailText |
Detailed description |
|
detailTextType |
Detailed description type: |
|
detailPicture |
Detail picture file identifier |
|
iblockSectionId |
Main section identifier |
|
iblockSection |
Array of identifiers of all sections the product is linked to |
|
type |
Product type: |
|
available |
Availability for purchase: |
|
bundle |
Whether the product has a bundle: |
|
quantity |
Available quantity |
|
quantityReserved |
Reserved quantity |
|
quantityTrace |
Whether quantity tracking is enabled: |
|
canBuyZero |
Whether purchase is allowed when the product is out of stock: |
|
subscribe |
Whether subscription to the product is allowed: |
|
vatId |
VAT rate identifier |
|
vatIncluded |
Whether VAT is included in the price: |
|
purchasingPrice |
Purchase price. Returned if the user has the "View purchase price" access permission |
|
purchasingCurrency |
Purchase price currency. Returned if the user has the "View purchase price" access permission |
|
barcodeMulti |
Unique barcodes for each item: |
|
weight |
Weight |
|
length |
Length |
|
width |
Width |
|
height |
Height |
|
measure |
Unit of measurement identifier |
|
recurSchemeLength |
Payment period length. Used only in the on-premise version for content sales |
|
recurSchemeType |
Time unit of the payment period. Used only in the on-premise version for content sales |
|
trialPriceId |
Product for trial payment. Used only in the on-premise version for content sales |
|
withoutOrder |
Renewal without placing an order: |
|
quantityTraceRaw |
Saved quantity tracking value: |
|
paymentType |
Payment type: |
|
subscribeRaw |
Saved subscription value: |
|
canBuyZeroRaw |
Saved value of purchase when out of stock: |
|
properties |
Product property values. The keys are |
A new parent product without variations gets type 6. After the first variation is added, the type changes to 3.
Error Handling
HTTP status: 400
{
"error": {
"code": "BITRIX_REST_V3_EXCEPTION_VALIDATION_DTOVALIDATIONEXCEPTION",
"message": "Error validating object.",
"validation": [
{
"message": "Required field \"name\" is empty.",
"field": "name"
}
]
}
}
|
Name |
Description |
|
error.code |
String error code. Use it to identify the type of exception |
|
error.message |
Text description of the error |
|
error.validation |
Array with error details. Present only in data validation errors |
|
error.validation[].field |
Name of the field where the validation error occurred |
|
error.validation[].message |
Description of the error related to the specified field |
Possible Error Codes
Object Validation Errors
Error Code: BITRIX_REST_V3_EXCEPTION_VALIDATION_DTOVALIDATIONEXCEPTION
|
Field |
Error description |
How to Fix |
|
|
Required field |
Pass |
|
|
Required field |
Pass |
|
|
Field |
Remove |
|
|
Field |
Remove |
Request Validation Errors
Error Code: BITRIX_REST_V3_EXCEPTION_VALIDATION_REQUESTVALIDATIONEXCEPTION
In some errors, the field field contains a numeric error code instead of the field name.
|
Field |
Error description |
How to Fix |
|
|
Required field |
Pass the |
|
|
This request requires data type |
Pass a number |
|
|
Iblock Not Found |
Pass the identifier of an existing catalog information block |
|
|
productType is not allowed for this catalog |
Pass the identifier of the product catalog information block |
|
|
VAT vatId is not exists |
Pass the identifier of an existing VAT rate |
|
|
User createdBy is not exists |
Pass the identifier of an existing user. A similar error is returned for |
|
|
Currency purchasingCurrency is not exists |
Pass the code of an existing currency |
|
|
The properties field accepts only the property keys PROPERTY_{id}, unknown keys: #KEYS# |
Pass only keys of the |
|
|
The properties field names one property by several keys: #KEYS# |
Pass each property under a single key |
Unknown Field Error
Error Code: BITRIX_REST_V3_EXCEPTION_UNKNOWNDTOPROPERTYEXCEPTION
|
Field |
Error description |
How to Fix |
|
|
Unknown field |
Pass in |
Access Error
Error Code: BITRIX_REST_V3_EXCEPTION_ACCESSDENIEDEXCEPTION
|
Field |
Error description |
How to Fix |
|
|
Access denied |
Check the user's permissions for the catalog and the information block. The error also occurs if the section from |
Statuses and System Error Codes
HTTP Status: 4xx, 5xx
The errors described below are returned by the REST API itself, not by the logic of a specific method. They can arrive in response to any method.
|
Status |
Code |
Description |
|
|
|
An internal server error has occurred. Retry the call, and if the error persists, contact the server administrator or Bitrix24 technical support |
|
|
|
The server returned an unexpected response. Retry the call, and if the error persists, contact the server administrator or Bitrix24 technical support |
|
|
|
The request intensity limit has been exceeded |
|
|
|
The method is blocked because the request resource intensity limit has been exceeded. The block is lifted automatically once the accumulated execution time of the method no longer exceeds the limit |
|
|
|
The request contains no authorization data: neither an access token nor a webhook code was passed |
|
|
|
Methods are called over the HTTPS protocol only |
|
|
|
The REST API is blocked due to overload. This is a manual individual block. To have it lifted, contact Bitrix24 technical support |
|
|
|
REST API access is not active for this account. In Bitrix24 Cloud, check the current plan or trial status: Vibe+ plans include REST API access, while Essentials plans do not. A webhook receives a different error message — |
|
|
|
No active webhook with the specified user identifier and secret code was found |
|
|
|
No method with this name was found. The name is misspelled, the method does not exist in the REST API, or it is unavailable without the required scope |
|
|
|
The request requires broader permissions than the token has: for a webhook these are the permissions granted to it, for an application it is the scope. For an application, the error message ends with |
|
|
|
The access token has expired |
|
|
|
The application is installed, but the Bitrix24 administrator has granted access to it only to specific users |
|
|
|
The public part of the site is closed. To open it on an on-premise installation, disable the "Temporary closure of the public part of the site" option. Path to the setting: Desktop > Settings > Product Settings > Module Settings > Main Module > Temporary closure of the public part of the site |
Continue Learning
- Update Parent Product Fields v 3.0 catalog.product.sku.update
- Get Parent Product Field Values v 3.0 catalog.product.sku.get
- Get List of Parent Products v 3.0 catalog.product.sku.list
- Delete Parent Product v 3.0 catalog.product.sku.delete
- Download Parent Product Files v 3.0 catalog.product.sku.download
- Get List of Parent Product Fields v 3.0 catalog.product.sku.field.list
- Get Parent Product Field catalog.product.sku.field.get