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

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
name string yes Offer name
iblockId number yes Offers catalog ID — the catalog that has productIblockId set. List: GET /v1/catalogs
parentId object no Link 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
active boolean no Whether the offer is active. Defaults to true
iblockSectionId number no Catalog section ID. List: GET /v1/catalog-sections
measure number no Unit of measure ID. List: GET /v1/catalog-measures
weight number no Weight of one product unit
vatIncluded boolean no VAT included in the price
canBuyZero boolean no Allow purchase when stock is zero
quantityTrace boolean no Enable quantity tracking
subscribe boolean no Allow subscription to the product
barcodeMulti boolean no Separate barcodes for product units
withoutOrder boolean no Available for ordering without stock on hand
purchasingPrice number no Purchase price
purchasingCurrency string no Purchase price currency. List: GET /v1/currencies
quantity number no Stock 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
success boolean Always true on success
data object Full 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
400 MISSING_REQUIRED_FIELDS A required field was not passed — the message names it. An empty body is rejected with a message about iblockId
400 READONLY_FIELD The body contains a read-only field, for example available
422 BITRIX_ERROR No parent product with the ID from parentId exists (Parent product not found.)
422 BITRIX_ERROR iblockId holds the ID of a product catalog, not an offers catalog (productType is not allowed for this catalog)
422 BITRIX_ERROR No catalog with the specified iblockId exists (iblock is not catalog)
403 SCOPE_DENIED The key lacks the catalog scope
401 MISSING_API_KEY The X-Api-Key header was not passed

Full list of common API errors — Errors.

See also