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

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

Catalog offers

Catalog offers: list, retrieve, create, update, and delete. An offer describes a specific variant of a parent product — for example, a T-shirt size — and is stored in a separate offer catalog. The parent product is created in Catalog SKUs, and the offer's sale prices are set in Catalog prices.

Bitrix24 API: catalog.product.offer.* Scope: catalog

Create an offer

POST /v1/catalog-offers

Creates a product offer in the offers catalog and links it to a parent product. Fields are passed flat at the JSON root.

Request fields (body)

Field Type Required Description
Fieldname Typestring Requiredyes DescriptionOffer name
FieldiblockId Typenumber Requiredyes DescriptionOffers catalog ID — the catalog that has productIblockId set. List: GET /v1/catalogs
FieldparentId Typeobject Requiredno DescriptionLink to the parent product: { "value": "<ID>" }, with the ID as a string. List: GET /v1/catalog-skus. Without this field, a free offer with type: 5 is created
Fieldactive Typeboolean Requiredno DescriptionWhether the offer is active. Defaults to true
FieldiblockSectionId Typenumber Requiredno DescriptionCatalog section ID. List: GET /v1/catalog-sections
Fieldmeasure Typenumber Requiredno DescriptionUnit of measure ID. List: GET /v1/catalog-measures
Fieldweight Typenumber Requiredno DescriptionWeight of one product unit
FieldvatIncluded Typeboolean Requiredno DescriptionVAT included in the price
FieldcanBuyZero Typeboolean Requiredno DescriptionAllow purchase when stock is zero
FieldquantityTrace Typeboolean Requiredno DescriptionEnable quantity tracking
Fieldsubscribe Typeboolean Requiredno DescriptionAllow subscription to the product
FieldbarcodeMulti Typeboolean Requiredno DescriptionSeparate barcodes for product units
FieldwithoutOrder Typeboolean Requiredno DescriptionAvailable for ordering without stock on hand
FieldpurchasingPrice Typenumber Requiredno DescriptionPurchase price
FieldpurchasingCurrency Typestring Requiredno DescriptionPurchase price currency. List: GET /v1/currencies
Fieldquantity Typenumber Requiredno DescriptionStock on hand

The symbolic code, dimensions, texts, images and catalog properties propertyNNN are listed in Offer fields. The selling price is set separately — in POST /v1/catalog-prices with the offer id in productId.

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/catalog-offers" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Basic T-shirt, size M",
    "iblockId": 27,
    "parentId": { "value": "7189" },
    "measure": 9,
    "purchasingPrice": 450,
    "purchasingCurrency": "USD"
  }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/catalog-offers" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Basic T-shirt, size M",
    "iblockId": 27,
    "parentId": { "value": "7189" },
    "measure": 9,
    "purchasingPrice": 450,
    "purchasingCurrency": "USD"
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/catalog-offers', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Basic T-shirt, size M',
    iblockId: 27,
    parentId: { value: '7189' },
    measure: 9,
    purchasingPrice: 450,
    purchasingCurrency: 'USD',
  }),
})

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

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/catalog-offers', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Basic T-shirt, size M',
    iblockId: 27,
    parentId: { value: '7189' },
    measure: 9,
    purchasingPrice: 450,
    purchasingCurrency: 'USD',
  }),
})

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

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionFull object of the created offer. The field set is the same as in GET /v1/catalog-offers/:id

Response example

The main fields are shown.

JSON 
{
  "success": true,
  "data": {
    "id": 7191,
    "iblockId": 27,
    "iblockSectionId": null,
    "name": "Basic T-shirt, size M",
    "parentId": { "value": "7189", "valueId": "3895" },
    "type": 4,
    "active": true,
    "available": true,
    "code": null,
    "xmlId": "7191",
    "measure": 9,
    "purchasingPrice": 450,
    "purchasingCurrency": "USD",
    "quantity": null,
    "quantityTrace": true,
    "canBuyZero": true,
    "vatIncluded": false,
    "createdBy": 1295,
    "dateCreate": "2026-10-08T18:41:55.000Z",
    "timestampX": "2026-10-08T18:41:55.000Z"
  }
}

Error response example

400 — a required field was not passed:

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

Errors

HTTP Code Description
HTTP400 CodeMISSING_REQUIRED_FIELDS DescriptionA required field was not passed — the message names it. An empty body is rejected with a message about iblockId
HTTP400 CodeREADONLY_FIELD DescriptionThe body contains a read-only field, for example available
HTTP422 CodeBITRIX_ERROR DescriptionNo parent product with the ID from parentId exists (Parent product not found.)
HTTP422 CodeBITRIX_ERROR DescriptioniblockId holds the ID of a product catalog, not an offers catalog (productType is not allowed for this catalog)
HTTP422 CodeBITRIX_ERROR DescriptionNo catalog with the specified iblockId exists (iblock is not catalog)
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the catalog scope
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header was not passed

Full list of common API errors — Errors.

See also