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

Create a delivery service

POST /v1/delivery-services

Creates a delivery service and its profiles using a handler already registered in the Bitrix24 account.

Pass fields at the JSON root without a fields wrapper.

Request fields (body)

Field Type Required Description
Fieldname Typestring Requiredyes DescriptionService name. Empty strings and "0" are not accepted
Fieldcurrency Typestring Requiredyes DescriptionNonempty currency code, for example USD. List currencies
FieldrestCode Typestring Requiredyes DescriptionNonempty code value from the handler list
Fielddescription Typestring Requiredno DescriptionService description
Fieldsort Typeinteger Requiredno DescriptionSort index
Fieldactive Typestring Requiredno DescriptionService activity: Y or N. Defaults to Y when omitted
Fieldlogo Typestring[] Requiredno DescriptionTwo nonempty elements: the file name and its base64 content. The decoded file must be at most 2 MiB
Fieldconfig Typeobject | array Requiredno DescriptionSettings for the selected handler in Bitrix24 format. Nested keys and their case are preserved

The body must contain at least one field. The JSON body must be at most 3 MiB.

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/delivery-services" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Courier delivery",
  "restCode": "my_delivery_handler",
  "currency": "USD",
  "active": "N"
}'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/delivery-services" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Courier delivery",
  "restCode": "my_delivery_handler",
  "currency": "USD",
  "active": "N"
}'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/delivery-services', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Courier delivery',
    restCode: 'my_delivery_handler',
    currency: 'USD',
    active: 'N',
  }),
})

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

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/delivery-services', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Courier delivery',
    restCode: 'my_delivery_handler',
    currency: 'USD',
    active: 'N',
  }),
})

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

Response fields

HTTP status: 201 Created. data contains the required parent object and profiles array.

RO marks read-only fields.

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue on success
Fielddata Typeobject DescriptionCreated service and its profiles
Fielddata.parent Typeobject DescriptionParent delivery service
Fielddata.profiles Typeobject[] DescriptionCreated delivery profiles
Fielddata.parent.id Typeinteger DescriptionService ID. RO
Fielddata.parent.parentId Typeinteger | null DescriptionParent service ID or null. RO
Fielddata.parent.name Typestring | null DescriptionService name
Fielddata.parent.active Typestring | null DescriptionService activity
Fielddata.parent.description Typestring | null DescriptionService description
Fielddata.parent.currency Typestring | null DescriptionCurrency code
Fielddata.parent.sort Typeinteger | null DescriptionSort index
Fielddata.parent.logotype Typeinteger | null DescriptionLogo file ID, not a URL, or null. RO. Use logo to write the file
Fielddata.profiles[].id Typeinteger DescriptionService ID. RO
Fielddata.profiles[].parentId Typeinteger | null DescriptionParent service ID or null. RO
Fielddata.profiles[].name Typestring | null DescriptionService name
Fielddata.profiles[].active Typestring | null DescriptionService activity
Fielddata.profiles[].description Typestring | null DescriptionService description
Fielddata.profiles[].currency Typestring | null DescriptionCurrency code
Fielddata.profiles[].sort Typeinteger | null DescriptionSort index
Fielddata.profiles[].logotype Typeinteger | null DescriptionLogo file ID, not a URL, or null. RO. Use logo to write the file

Response example

JSON 
{
  "success": true,
  "data": {
    "parent": {
      "id": 85,
      "parentId": null,
      "name": "Courier delivery",
      "active": "N",
      "description": "",
      "currency": "USD",
      "sort": 100,
      "logotype": null
    },
    "profiles": [
      {
        "id": 87,
        "parentId": 85,
        "name": "Delivery profile 1",
        "active": "N",
        "description": "Taxi Delivery",
        "currency": "USD",
        "sort": 100,
        "logotype": null
      },
      {
        "id": 89,
        "parentId": 85,
        "name": "Delivery profile 2",
        "active": "N",
        "description": "Cargo Delivery",
        "currency": "USD",
        "sort": 100,
        "logotype": null
      }
    ]
  }
}

Error response example

400 — the body is an empty JSON object:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_REQUIRED_FIELDS",
    "message": "A nonempty JSON object is required"
  }
}

Errors

HTTP error.code Description
HTTP400 error.codeMISSING_REQUIRED_FIELDS DescriptionThe body is not a nonempty JSON object, a required field is missing, or the name is empty
HTTP400 error.codeINVALID_PARAMS DescriptionA field has an invalid type, or logo contains an invalid file
HTTP400 error.codeREADONLY_FIELD DescriptionThe body contains a field absent from the request field table, including logotype
HTTP413 error.codePAYLOAD_TOO_LARGE DescriptionThe logo file exceeds 2 MiB, or the JSON body exceeds 3 MiB
HTTP422 error.codeBITRIX_ERROR DescriptionBitrix24 rejected creation. See error.message for the reason
HTTP502 error.codeBITRIX_RESPONSE_INVALID DescriptionThe creation response does not contain valid service and profile objects
HTTP403 error.codeBITRIX_ACCESS_DENIED DescriptionThe user lacks permission to create the service
HTTP401 error.codeTOKEN_MISSING DescriptionThe API key has no configured Bitrix24 credentials
HTTP403 error.codeSCOPE_DENIED DescriptionThe API key lacks the delivery scope
HTTP403 error.codeWRITE_BLOCKED_READONLY_KEY DescriptionThe API key is in read-only mode

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

See also