Create Delivery Request CREATE_DELIVERY_REQUEST_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 CREATE_DELIVERY_REQUEST_URL parameter passed when creating a delivery handler using sale.delivery.handler.add. The external system must create a delivery order and return its identifier in JSON format.
Request Parameters
|
Name |
Description |
|
SHIPMENTS |
Information about shipments (detailed description provided below) |
SHIPMENT
|
Name |
Description |
|
Identifier of the shipment. If the calculation is based on an unsaved shipment, the parameter value will be You can obtain shipment identifiers using the sale.shipment.list method |
|
|
DELIVERY_SERVICE |
Information about the selected delivery service, its profile, and settings (detailed description provided below). May be |
|
PRICE |
Total cost of goods for the client in the shipment |
|
CURRENCY |
Currency code of the cost |
|
WEIGHT |
Total weight of goods in the shipment (in grams) |
|
PROPERTY_VALUES |
Array containing the property values of the shipment (detailed description provided below) |
|
ITEMS |
Array containing all the goods included in the shipment (detailed description provided below) |
|
EXTRA_SERVICES_VALUES |
Array containing a list of necessary additional services selected for delivery (detailed description provided below) |
|
RESPONSIBLE_CONTACT |
Information about the employee responsible for delivery on the Bitrix24 side (detailed description provided below). May be |
|
RECIPIENT_CONTACT |
Information about the shipment recipient (detailed description provided below). May be |
DELIVERY_SERVICE
|
Name |
Description |
|
Identifier of the delivery service |
|
|
CONFIG |
Values of the delivery service settings (detailed description provided below) |
|
PARENT |
Information about the parent delivery service (detailed description provided below). The field is absent if no parent service is specified |
PARENT
|
Name |
Description |
|
Identifier of the parent delivery service |
|
|
CONFIG |
Values of the parent delivery service settings (detailed description provided below) |
CONFIG
|
Name |
Description |
|
CODE |
Symbolic code of the setting |
|
VALUE |
Value of the setting |
PROPERTY_VALUES
|
Name |
Description |
|
Identifier of the shipment property. You can obtain the identifier of shipment properties using the sale.shipmentproperty.list method |
|
|
TYPE |
Type of the property. Possible values:
|
|
Value of the property. For the |
VALUE
|
Name |
Description |
|
LATITUDE |
Geographic latitude. May be |
|
LONGITUDE |
Geographic longitude. May be |
|
FIELDS |
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 |
Description |
|
POSTAL_CODE |
Postal code |
|
COUNTRY |
Country |
|
ADM_LEVEL_1 |
First-level administrative division unit (e.g., state or region) |
|
ADM_LEVEL_2 |
Second-level administrative division unit (e.g., district) |
|
ADM_LEVEL_3 |
Third-level administrative division unit |
|
ADM_LEVEL_4 |
Fourth-level administrative division unit |
|
LOCALITY |
Locality |
|
SUB_LOCALITY |
District or part of a locality |
|
SUB_LOCALITY_LEVEL_1 |
First-level subdivision of a locality |
|
SUB_LOCALITY_LEVEL_2 |
Second-level subdivision of a locality |
|
STREET |
Street |
|
BUILDING |
Building, house number |
|
ADDRESS_LINE_1 |
Address (street, building, house number) |
|
ADDRESS_LINE_2 |
Additional address line |
|
FLOOR |
Floor |
|
ROOM |
Room |
|
RECIPIENT_COMPANY |
Recipient company name |
|
RECIPIENT |
Recipient name |
|
PO_BOX |
Post office box number |
ITEMS
|
Name |
Description |
|
NAME |
Name of the product |
|
PRICE |
Price of a single item of the product |
|
CURRENCY |
Currency code of the price |
|
WEIGHT |
Weight of a single item of the product. May be |
|
QUANTITY |
Quantity of product units |
|
DIMENSIONS |
Dimensions of the cargo (detailed description provided below). May be |
DIMENSIONS
|
Name |
Description |
|
LENGTH |
Product length in millimeters |
|
WIDTH |
Product width in millimeters |
|
HEIGHT |
Product height in millimeters |
EXTRA_SERVICES_VALUES
|
Name |
Description |
|
Identifier of the service. You can obtain the identifiers of delivery service extra services using the sale.delivery.extra.service.get method |
|
|
CODE |
Symbolic code of the additional service |
|
VALUE |
Value. Depending on the type (sale_delivery_extra_service.TYPE) of the additional service, the value is formed differently:
|
RESPONSIBLE_CONTACT
|
Name |
Description |
|
NAME |
Full name of the contact |
|
PHONES |
Array of the contact's phone numbers (detailed description provided below) |
RECIPIENT_CONTACT
|
Name |
Description |
|
NAME |
Full name of the contact |
|
PHONES |
Array of the contact's phone numbers (detailed description provided below). The field is absent if no phone numbers are specified |
PHONES
|
Name |
Description |
|
TYPE |
Type of phone. Possible values:
|
|
VALUE |
Phone number |
Examples
Example JSON request:
{
"SHIPMENTS":[
{
"ID":4063,
"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":2
}
],
"RESPONSIBLE_CONTACT":{
"NAME":"Ronald Perez",
"PHONES":[
{
"TYPE":"MOBILE",
"VALUE":"+19097996161"
}
]
},
"RECIPIENT_CONTACT":{
"NAME":"James Johnson",
"PHONES":[
{
"TYPE":"WORK",
"VALUE":"+19097996162"
}
]
}
}
]
}
Response Parameters
The handler must return HTTP status 200 and a JSON object.
Required parameters are marked with *
|
Name |
Description |
|
SUCCESS* |
Result of creating a delivery order. Possible values:
|
|
REQUEST_ID* |
Identifier of the created delivery order in the external system. Required if |
|
REASON |
Reason why the delivery order was not created. Passed if |
REASON Object
|
Name |
Description |
|
TEXT* |
Description of the error |
Example Response with Successful Delivery Request Creation
{
"SUCCESS": "Y",
"REQUEST_ID": "4757aca4931a4f029f49c0db4374d13d"
}
Example Response with Delivery Order Creation Error
{
"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 order creation unsuccessful. Provide an explanation in REASON.TEXT. If REASON.TEXT is absent or empty, Bitrix24 uses the standard error message.
When SUCCESS = Y, the REQUEST_ID field must contain a non-empty string. A response without an identifier is considered invalid.