## 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 |
|---|---|---|---|
| `name` | string | yes | Service name. Empty strings and `"0"` are not accepted |
| `currency` | string | yes | Nonempty currency code, for example `USD`. [List currencies](/docs/entities/currencies/list) |
| `restCode` | string | yes | Nonempty `code` value from the [handler list](/docs/entities/delivery-services/handlers) |
| `description` | string | no | Service description |
| `sort` | integer | no | Sort index |
| `active` | string | no | Service activity: `Y` or `N`. Defaults to `Y` when omitted |
| `logo` | string[] | no | Two nonempty elements: the file name and its base64 content. The decoded file must be at most 2 MiB |
| `config` | object \| array | no | Settings 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

```bash
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

```bash
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 |
|---|---|---|
| `success` | boolean | `true` on success |
| `data` | object | Created service and its profiles |
| `data.parent` | object | Parent delivery service |
| `data.profiles` | object[] | Created delivery profiles |
| `data.parent.id` | integer | Service ID. RO |
| `data.parent.parentId` | integer \| null | Parent service ID or `null`. RO |
| `data.parent.name` | string \| null | Service name |
| `data.parent.active` | string \| null | Service activity |
| `data.parent.description` | string \| null | Service description |
| `data.parent.currency` | string \| null | Currency code |
| `data.parent.sort` | integer \| null | Sort index |
| `data.parent.logotype` | integer \| null | Logo file ID, not a URL, or `null`. RO. Use `logo` to write the file |
| `data.profiles[].id` | integer | Service ID. RO |
| `data.profiles[].parentId` | integer \| null | Parent service ID or `null`. RO |
| `data.profiles[].name` | string \| null | Service name |
| `data.profiles[].active` | string \| null | Service activity |
| `data.profiles[].description` | string \| null | Service description |
| `data.profiles[].currency` | string \| null | Currency code |
| `data.profiles[].sort` | integer \| null | Sort index |
| `data.profiles[].logotype` | integer \| null | Logo 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 |
|---|---|---|
| 400 | `MISSING_REQUIRED_FIELDS` | The body is not a nonempty JSON object, a required field is missing, or the name is empty |
| 400 | `INVALID_PARAMS` | A field has an invalid type, or `logo` contains an invalid file |
| 400 | `READONLY_FIELD` | The body contains a field absent from the request field table, including `logotype` |
| 413 | `PAYLOAD_TOO_LARGE` | The logo file exceeds 2 MiB, or the JSON body exceeds 3 MiB |
| 422 | `BITRIX_ERROR` | Bitrix24 rejected creation. See `error.message` for the reason |
| 502 | `BITRIX_RESPONSE_INVALID` | The creation response does not contain valid service and profile objects |
| 403 | `BITRIX_ACCESS_DENIED` | The user lacks permission to create the service |
| 401 | `TOKEN_MISSING` | The API key has no configured Bitrix24 credentials |
| 403 | `SCOPE_DENIED` | The API key lacks the `delivery` scope |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | The API key is in read-only mode |

For the full list of common API errors, see [Errors](/docs/errors).

## See also

- [Delivery services](/docs/entities/delivery-services)
- [List delivery services](/docs/entities/delivery-services/list)
- [Get a delivery service](/docs/entities/delivery-services/get)
- [Update a delivery service](/docs/entities/delivery-services/update)
- [Delete a delivery service](/docs/entities/delivery-services/delete)
- [List delivery handlers](/docs/entities/delivery-services/handlers)
- [Batch](/docs/batch)
- [Limits and optimization](/docs/optimization)