Calculate Delivery Costs CALCULATE_URL

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

Bitrix24 sends an HTTP POST request to the address from the CALCULATE_URL parameter passed when creating a delivery handler using sale.delivery.handler.add. The external system must calculate the delivery cost and return the result in JSON format.

Request Parameters

Name `type`	Description
SHIPMENT `object`	Information about the shipment (detailed description provided below)

SHIPMENT

Name `type`	Description
ID `sale_order_shipment.id`	Identifier of the shipment. If the calculation is based on an unsaved shipment, the parameter value will be `null`. You can obtain shipment identifiers using the sale.shipment.list method
DELIVERY_SERVICE `object`	Information about the selected delivery service, its profile, and settings (detailed description provided below). May be `null` if the delivery service is not found
PRICE `double`	Total cost of goods for the client in the shipment
CURRENCY `crm_currency.CURRENCY`	Currency code of the cost
WEIGHT `double`	Total weight of goods in the shipment (in grams)
PROPERTY_VALUES `object[]`	Array containing the property values of the shipment (detailed description provided below)
ITEMS `object[]`	Array containing all the goods included in the shipment (detailed description provided below)
EXTRA_SERVICES_VALUES `object[]`	Array containing a list of necessary additional services selected for delivery (detailed description provided below)
RESPONSIBLE_CONTACT `object`	Information about the employee responsible for delivery on the Bitrix24 side (detailed description provided below). May be `null` if the responsible person is not specified or not found
RECIPIENT_CONTACT `object`	Information about the shipment recipient (detailed description provided below). May be `null` if the recipient contact is unavailable

DELIVERY_SERVICE

Name `type`	Description
ID `sale_delivery_service.ID`	Identifier of the delivery service
CONFIG `object[]`	Values of the delivery service settings (detailed description provided below)
PARENT `object`	Information about the parent delivery service (detailed description provided below). The field is absent if no parent service is specified

PARENT

Name `type`	Description
ID `sale_delivery_service.ID`	Identifier of the parent delivery service
CONFIG `object[]`	Values of the parent delivery service settings (detailed description provided below)

CONFIG

Name `type`	Description
CODE `string`	Symbolic code of the setting
VALUE `any`	Value of the setting

PROPERTY_VALUES

Name `type`	Description
ID `sale_shipment_property.id`	Identifier of the shipment property. You can obtain the identifier of shipment properties using the sale.shipmentproperty.list method
TYPE `string`	Type of the property. Possible values: `STRING` — string `ADDRESS` — address
VALUE `string` \| `object`	Value of the property. For the `object` type, detailed description provided below. May be `null` if the address value is absent

VALUE

Name `type`	Description
LATITUDE `double`	Geographic latitude. May be `null`
LONGITUDE `double`	Geographic longitude. May be `null`
FIELDS `object`	Detailed information about the delivery address (detailed description provided below)

FIELDS

The object structure depends on which address components are filled in. Bitrix24 passes the available fields from the following list.

Name `type`	Description
POSTAL_CODE `string`	Postal code
COUNTRY `string`	Country
ADM_LEVEL_1 `string`	First-level administrative division unit (e.g., state or region)
ADM_LEVEL_2 `string`	Second-level administrative division unit (e.g., district)
ADM_LEVEL_3 `string`	Third-level administrative division unit
ADM_LEVEL_4 `string`	Fourth-level administrative division unit
LOCALITY `string`	Locality
SUB_LOCALITY `string`	District or part of a locality
SUB_LOCALITY_LEVEL_1 `string`	First-level subdivision of a locality
SUB_LOCALITY_LEVEL_2 `string`	Second-level subdivision of a locality
STREET `string`	Street
BUILDING `string`	Building, house number
ADDRESS_LINE_1 `string`	Address (street, building, house number)
ADDRESS_LINE_2 `string`	Additional address line
FLOOR `string`	Floor
ROOM `string`	Room
RECIPIENT_COMPANY `string`	Recipient company name
RECIPIENT `string`	Recipient name
PO_BOX `string`	Post office box number

ITEMS

Name `type`	Description
NAME `string`	Name of the product
PRICE `double`	Price of a single item of the product
CURRENCY `crm_currency.CURRENCY`	Currency code of the price
WEIGHT `double`	Weight of a single item of the product. May be `null` if the weight is not specified
QUANTITY `double`	Quantity of product units
DIMENSIONS `object`	Dimensions of the cargo (detailed description provided below). May be `null` if the dimensions are not fully specified

DIMENSIONS

Name `type`	Description
LENGTH `double`	Product length in millimeters
WIDTH `double`	Product width in millimeters
HEIGHT `double`	Product height in millimeters

EXTRA_SERVICES_VALUES

Name `type`	Description
ID `sale_delivery_extra_service.ID`	Identifier of the service. You can obtain the identifiers of delivery service extra services using the sale.delivery.extra.service.get method
CODE `string`	Symbolic code of the additional service
VALUE `string` \| `double`	Value. Depending on the type (sale_delivery_extra_service.TYPE) of the additional service, the value is formed differently: `checkbox` `Y` — if the service is required `N` — if the service is not required `enum` — string containing the symbolic code of the selected value from the service list `quantity` — number reflecting the required amount for the additional service

RESPONSIBLE_CONTACT

Name `type`	Description
NAME `string`	Full name of the contact
PHONES `object[]`	Array of the contact's phone numbers (detailed description provided below)

RECIPIENT_CONTACT

Name `type`	Description
NAME `string`	Full name of the contact
PHONES `object[]`	Array of the contact's phone numbers (detailed description provided below). The field is absent if no phone numbers are specified

PHONES

Name
type

Description

TYPE
string

Type of phone. Possible values:

WORK — work
MOBILE — mobile
HOME — home
FAX — fax
PAGER — pager

VALUE
string

Phone number

Example Request

{
            "SHIPMENT":{
                "ID":4060,
                "DELIVERY_SERVICE":{
                    "ID":225,
                    "CONFIG":[
                        {
                            "CODE":"PROFILE_TYPE",
                            "VALUE":"CARGO"
                        }
                    ],
                    "PARENT":{
                        "ID":223,
                        "CONFIG":[
                            {
                                "CODE":"SETTING_1",
                                "VALUE":"String Example Value"
                            }
                        ]
                    }
                },
                "PRICE":179998,
                "CURRENCY":"USD",
                "WEIGHT":600,
                "PROPERTY_VALUES":[
                    {
                        "ID":100,
                        "TYPE":"ADDRESS",
                        "VALUE":{
                            "LATITUDE":55.726421,
                            "LONGITUDE":37.61187,
                            "FIELDS":{
                                "COUNTRY":"USA",
                                "ADM_LEVEL_1":"Los Angeles",
                                "ADM_LEVEL_2":"Los Angeles",
                                "ADM_LEVEL_3":"South",
                                "LOCALITY":"Los Angeles",
                                "SUB_LOCALITY_LEVEL_1":"Central",
                                "STREET":"Flowers Street",
                                "BUILDING":"9",
                                "ADDRESS_LINE_1":"Flowers Street, 9"
                            }
                        }
                    },
                    {
                        "ID":101,
                        "TYPE":"ADDRESS",
                        "VALUE":{
                            "LATITUDE":55.724779,
                            "LONGITUDE":37.614294,
                            "FIELDS":{
                                "POSTAL_CODE":"115162",
                                "COUNTRY":"USA",
                                "ADM_LEVEL_1":"Los Angeles",
                                "ADM_LEVEL_2":"South",
                                "LOCALITY":"Los Angeles",
                                "STREET":"Flowers Street",
                                "BUILDING":"13 b10",
                                "ADDRESS_LINE_1":"Flowers Street, 13 b10"
                            }
                        }
                    }
                ],
                "ITEMS":[
                    {
                        "NAME":"iPhone 14",
                        "PRICE":89999,
                        "WEIGHT":300,
                        "CURRENCY":"USD",
                        "QUANTITY":2,
                        "DIMENSIONS":{
                            "WIDTH":400,
                            "HEIGHT":80,
                            "LENGTH":500
                        }
                    }
                ],
                "EXTRA_SERVICES_VALUES":[
                    {
                        "ID":138,
                        "CODE":"cargo_type",
                        "VALUE":"small_package"
                    },
                    {
                        "ID":137,
                        "CODE":"door_delivery",
                        "VALUE":"Y"
                    },
                    {
                        "ID":139,
                        "CODE":"some_quantity_service",
                        "VALUE":3
                    }
                ],
                "RESPONSIBLE_CONTACT":{
                    "NAME":"Ronald Perez",
                    "PHONES":[
                        {
                            "TYPE":"MOBILE",
                            "VALUE":"+19097996161"
                        }
                    ]
                },
                "RECIPIENT_CONTACT":{
                    "NAME":"James Johnson",
                    "PHONES":[
                        {
                            "TYPE":"WORK",
                            "VALUE":"+19097996161"
                        }
                    ]
                }
            }
        }

Response Parameters

The handler must return HTTP status 200 and a JSON object.

Required parameters are marked with *

Name `type`	Description
SUCCESS* `string`	Indicator of the success of the delivery cost calculation. Possible values: `Y` — cost calculated successfully `N` — an error occurred while attempting to calculate the cost
PRICE `double`	Calculated delivery cost in the currency of the delivery service
PERIOD_DESCRIPTION `string`	Text description of the delivery period
PERIOD_FROM `integer`	Lower bound of the delivery period in the units specified in `PERIOD_TYPE`
PERIOD_TO `integer`	Upper bound of the delivery period in the units specified in `PERIOD_TYPE`
PERIOD_TYPE `string`	Unit of measurement for the delivery period. Possible values: `MIN` — minutes `H` — hours `D` — days `M` — months
DESCRIPTION `string`	Additional description of the calculation result
REASON `object`	Reason for the error. Provided in case of an unsuccessful cost calculation attempt (detailed description provided below)

REASON Object

Name `type`	Description
TEXT* `string`	Description of the error

Example Response with Successful Cost Calculation

{
            "SUCCESS": "Y",
            "PRICE": 79.99,
            "PERIOD_DESCRIPTION": "1–2 days",
            "PERIOD_FROM": 1,
            "PERIOD_TO": 2,
            "PERIOD_TYPE": "D",
            "DESCRIPTION": "Door-to-door courier delivery"
        }

Example Response with Error in Cost Calculation

{
            "SUCCESS": "N",
            "REASON": {
                "TEXT": "Delivery is not available for the specified address"
            }
        }

Error Handling

If SUCCESS is absent or differs from Y, Bitrix24 considers the calculation unsuccessful. Provide an explanation in REASON.TEXT. If REASON.TEXT is absent or empty, Bitrix24 uses the standard delivery calculation error message.

Continue Learning

Was the article helpful?

Webhooks for Delivery Operations

Create Delivery Request

Calculate Delivery Costs CALCULATE_URL

Request ParametersRequest Parameters

SHIPMENTSHIPMENT

DELIVERY_SERVICEDELIVERY_SERVICE

PARENTPARENT

CONFIGCONFIG

PROPERTY_VALUESPROPERTY_VALUES

VALUEVALUE

FIELDSFIELDS

ITEMSITEMS

DIMENSIONSDIMENSIONS

EXTRA_SERVICES_VALUESEXTRA_SERVICES_VALUES

RESPONSIBLE_CONTACTRESPONSIBLE_CONTACT

RECIPIENT_CONTACTRECIPIENT_CONTACT

PHONESPHONES

Example RequestExample Request

Response ParametersResponse Parameters

REASON ObjectREASON Object

Example Response with Successful Cost CalculationExample Response with Successful Cost Calculation

Example Response with Error in Cost CalculationExample Response with Error in Cost Calculation

Error HandlingError Handling

Continue LearningContinue Learning