Adds an order

Adds order information to the database.

Request

POST

https://courier.yandex.ru/api/v1/companies/{company_id}/orders

Path parameters

Name

Description

company_id*

Type: integer

Company ID used in requests to the Track & Trace API.

Body

application/json

{
    "address": "string",
    "amount": 0,
    "comments": "string",
    "customer_name": "string",
    "description": "string",
    "lat": 0,
    "lon": 0,
    "number": "string",
    "customer_number": "string",
    "payment_type": "cash",
    "payment_status": "paid",
    "phone": "string",
    "route_id": 0,
    "service_duration_s": 0,
    "shared_service_duration_s": 0,
    "status": "string",
    "volume": 0,
    "weight": 0,
    "shared_with_company_ids": [
        0
    ],
    "mark_delivered_radius": null,
    "eta_type": null,
    "time_interval": "string",
    "route_number": "string",
    "shared_with_company_numbers": [
        "string"
    ],
    "type": "string",
    "refined_lat": 0,
    "refined_lon": 0,
    "notifications": [
        {
            "type": "before_arrival"
        }
    ],
    "show_yandex_pay_button": false
}

Name	Description
address*	Type: string Delivery address in text format.
lat*	Type: number<float> Latitude of the delivery point.
lon*	Type: number<float> Longitude of the delivery point.
number*	Type: string Order number. Used for syncing with the delivery company's system. Max length: `80`
time_interval*	Type: string Desired delivery time interval. The following formats are supported: "T - T" or "T-T", where T is the time in HH, HH:MM, or HH:MM:SS format. ISO 8601, for example, 2018-09-06T10:15:00+03:00/2018-09-06T12:45:00+03:00.
amount	Type: number<float> Order price in rubles. Min value: `0`
comments	Type: string Order comments.
customer_name	Type: string Recipient's name. Max length: `1023`
customer_number	Type: string Customer's number in the delivery company database. Max length: `128`
description	Type: string Order description. Max length: `1023`
eta_type	Type: string ETA type. Affects the time of notification and automatic delivery detection. `arrival_time` — countdown starts from the moment the courier arrives at the point; `delivery_time` — countdown does not start until the start of the delivery window. Default: `null`
mark_delivered_radius	Type: number<float> Radius in meters. If `null`, `depot.mark_delivered_radius` or `company.mark_delivered_radius` is used instead. Order is marked as delivered automatically if `mark_delivered_enabled` is `true` and courier spent at least `mark_delivered_service_time_coefficient * (order.service_duration_s + order.shared_service_duration_s)` seconds within `mark_delivered_radius` meters from the order's location. Default: `null` Min value: `0` Max value: `10000`
notifications	Type: OrderNotification[] List of push notification settings.
payment_status	Type: string Payment status. Possible values: `paid` — The order is already paid. `unpaid` — The order is not paid yet. Enum: `paid`, `unpaid`, `null`
payment_type	Type: string Payment type. Possible values: `cash` — The order will be paid in cash. `card` — The order will be paid using bank card. `prepaid` — The order is paid and no additional payment is needed. `yandex_pay` — Payment via Yandex Pay. Can only be set internally. Enum: `cash`, `card`, `prepaid`, `yandex_pay`, `null`
phone	Type: string The recipient's phone number.
refined_lat	Type: number<float> Latitude of the real (refined by courier) delivery point.
refined_lon	Type: number<float> Logitude of the real (refined by courier) delivery point.
route_id	Type: integer Route ID used in requests to the Track & Trace API.
route_number	Type: string Route number. Used for syncing with the delivery company's system. You must specify `route_id` or `route_number` in the request to create a new order. If both `route_id` or `route_number` are specified `route_number` is used.
service_duration_s	Type: integer Expected time the courier will need to pass the order to the recipient, including going up to the floor and receiving payment. Default value: 600 seconds.
shared_service_duration_s	Type: integer Service duration at the location, which can be shared with other orders at the same location. Shared service duration can include operations as parking a car, delivering documents, etc. Default value: 0 seconds.
shared_with_company_ids	Type: number[] IDs of the companies that can access the order information. The following information is provided: Full information about the order. General description of the route this order is a part of. General description of the depot used in this order. General information about the delivery company (name and logo). If both `shared_with_company_numbers` and `shared_with_company_ids` are specified `shared_with_company_numbers` is used.
shared_with_company_numbers	Type: string[] Numbers of the companies that can access the order information. The following information is provided: Full information about the order. General description of the route this order is a part of. General description of the depot used in this order. General information about the delivery company (name and logo). If both `shared_with_company_numbers` and `shared_with_company_ids` are specified `shared_with_company_numbers` is used.
show_yandex_pay_button	Type: boolean Show Yandex Pay button.
status	Type: string The current order status. Possible values: new — The order was created. confirmed — The order delivery time was set (confirmed with recipient). finished — The order was delivered. partially_finished — The order was delivered only partially. Order status can be set to `partially_finished` only for companies with `company.partially_finished_status_enabled` flag equals `true`. cancelled — The order was canceled. postponed — The order is postponed or the courier couldn't contact the customer.
type	Type: string Type of order. Possible values — `delivery`, `pickup`, `drop_off`.
volume	Type: number<float> Order volume.
weight	Type: number<float> Order weight.

OrderNotification

Name

Description

type

Type: string

Notification type.

Enum: before_arrival

Responses

200 OK

Order information was registered in the database.

Body

application/json

{
    "address": "string",
    "amount": 0,
    "comments": "string",
    "customer_name": "string",
    "description": "string",
    "lat": 0,
    "lon": 0,
    "number": "string",
    "customer_number": "string",
    "payment_type": "cash",
    "payment_status": "paid",
    "phone": "string",
    "route_id": 0,
    "service_duration_s": 0,
    "shared_service_duration_s": 0,
    "status": "string",
    "volume": 0,
    "weight": 0,
    "shared_with_company_ids": [
        0
    ],
    "mark_delivered_radius": null,
    "eta_type": null,
    "company_id": 0,
    "confirmed_at": "string",
    "delivered_at": "string",
    "history": [
        {
            "event": "string",
            "timestamp": 0,
            "time": "2019-05-27T14:18:52.000Z",
            "position": {
                "lat": 0,
                "lon": 0,
                "time": "string"
            },
            "used_mark_delivered_radius": 0,
            "source": {
                "initiator": "string"
            }
        }
    ],
    "id": 0,
    "status_log": [
        {
            "point": {
                "lat": 0,
                "lon": 0
            },
            "status": "string",
            "timestamp": 0
        }
    ],
    "shared_with_companies": [
        {
            "number": "string",
            "name": "string",
            "id": 0
        }
    ],
    "order_status_comments": [
        {
            "id": 0,
            "status": "string",
            "comment": "string"
        }
    ],
    "refined_lat": 0,
    "refined_lon": 0,
    "time_interval": "string",
    "time_interval_secs": [
        0
    ],
    "time_window": {
        "start": "2019-03-06T14:15:00.000Z",
        "end": "2019-03-06T14:16:30.000Z"
    }
}

Name	Description
address	Type: string Delivery address in text format.
amount	Type: number<float> Order price in rubles. Min value: `0`
comments	Type: string Order comments.
company_id	Type: integer Company ID used in requests to the Track & Trace API.
confirmed_at	Type: string<datetime> Time when the order was agreed.
customer_name	Type: string Recipient's name. Max length: `1023`
customer_number	Type: string Customer's number in the delivery company database. Max length: `128`
delivered_at	Type: string<datetime> The time when information about the order was recorded in Track & Trace API.
description	Type: string Order description. Max length: `1023`
eta_type	Type: string ETA type. Affects the time of notification and automatic delivery detection. `arrival_time` — countdown starts from the moment the courier arrives at the point; `delivery_time` — countdown does not start until the start of the delivery window. Default: `null`
history	Type: OrderHistoryItem[] History of events that change the order status.
id	Type: integer The ID of the order that is used in requests to the Track & Trace API.
lat	Type: number<float> Latitude of the delivery point.
lon	Type: number<float> Longitude of the delivery point.
mark_delivered_radius	Type: number<float> Radius in meters. If `null`, `depot.mark_delivered_radius` or `company.mark_delivered_radius` is used instead. Order is marked as delivered automatically if `mark_delivered_enabled` is `true` and courier spent at least `mark_delivered_service_time_coefficient * (order.service_duration_s + order.shared_service_duration_s)` seconds within `mark_delivered_radius` meters from the order's location. Default: `null` Min value: `0` Max value: `10000`
number	Type: string Order number. Used for syncing with the delivery company's system. Max length: `80`
order_status_comments	Type: OrderStatusUpdateComment[]
payment_status	Type: string Payment status. Possible values: `paid` — The order is already paid. `unpaid` — The order is not paid yet. Enum: `paid`, `unpaid`, `null`
payment_type	Type: string Payment type. Possible values: `cash` — The order will be paid in cash. `card` — The order will be paid using bank card. `prepaid` — The order is paid and no additional payment is needed. `yandex_pay` — Payment via Yandex Pay. Can only be set internally. Enum: `cash`, `card`, `prepaid`, `yandex_pay`, `null`
phone	Type: string The recipient's phone number.
refined_lat	Type: number<float> Latitude of the real (refined by courier) delivery point.
refined_lon	Type: number<float> Logitude of the real (refined by courier) delivery point.
route_id	Type: integer Route ID used in requests to the Track & Trace API.
service_duration_s	Type: integer Expected time the courier will need to pass the order to the recipient, including going up to the floor and receiving payment. Default value: 600 seconds.
shared_service_duration_s	Type: integer Service duration at the location, which can be shared with other orders at the same location. Shared service duration can include operations as parking a car, delivering documents, etc. Default value: 0 seconds.
shared_with_companies	Type: CompanyNumber[]
shared_with_company_ids	Type: number[] IDs of the companies that can access the order information. The following information is provided: Full information about the order. General description of the route this order is a part of. General description of the depot used in this order. General information about the delivery company (name and logo). If both `shared_with_company_numbers` and `shared_with_company_ids` are specified `shared_with_company_numbers` is used.
status	Type: string The current order status. Possible values: new — The order was created. confirmed — The order delivery time was set (confirmed with recipient). finished — The order was delivered. partially_finished — The order was delivered only partially. Order status can be set to `partially_finished` only for companies with `company.partially_finished_status_enabled` flag equals `true`. cancelled — The order was canceled. postponed — The order is postponed or the courier couldn't contact the customer.
status_log	Type: StatusLog[]
time_interval	Type: string Desired delivery time interval. The following formats are supported: "T - T" or "T-T", where T is the time in HH, HH:MM, or HH:MM:SS format. ISO 8601, for example, 2018-09-06T10:15:00+03:00/2018-09-06T12:45:00+03:00.
time_interval_secs	Type: number[] `time_interval` value converted into seconds from midnight.
time_window	Type: OrderGetWithNotificatons_time_window Allowed time window to visit location, in ISO 8601 format.
volume	Type: number<float> Order volume.
weight	Type: number<float> Order weight.

OrderHistoryItem

Name	Description
event	Type: string Name of the event that occurred. Possible values: ORDER_CREATED, START, ORDER_BECAME_NEXT, STATUS_UPDATE, INTERVAL_UPDATE, ARRIVAL, ORDER_VISIT, DEPARTURE.
position	Type: OrderHistoryPosition Courier position. Appears only in events ARRIVAL, ORDER_VISIT, DEPARTURE.
source	Type: OrderStatusUpdateSource Source of the event. Appears only in event STATUS_UPDATE.
time	Type: string<datetime> Event time in ISO 8601 format. The time zone of the order is used. Example: `Mon May 27 2019 17:18:52 GMT+0300 (Moscow Standard Time)`
timestamp	Type: number<float> Event time (UNIX timestamp).
used_mark_delivered_radius	Type: number<float> The value of order.mark_delivered_radius or depot.mark_delivered_radius or company.mark_delivered_radius that was used to mark the order as visited. Appears only in events ARRIVAL, ORDER_VISIT, DEPARTURE. Min value: `0` Max value: `10000`

OrderStatusUpdateComment

Name	Description
comment	Type: string Comment for order status update event.
id	Type: integer ID of the order status update event.
status	Type: string The current order status. Possible values: new — The order was created. confirmed — The order delivery time was set (confirmed with recipient). finished — The order was delivered. partially_finished — The order was delivered only partially. Order status can be set to `partially_finished` only for companies with `company.partially_finished_status_enabled` flag equals `true`. cancelled — The order was canceled. postponed — The order is postponed or the courier couldn't contact the customer.

CompanyNumber

Name	Description
number*	Type: string Company number.
id	Type: integer Company ID used in requests to the Track & Trace API.
name	Type: string Company name. Max length: `80`

StatusLog

Name	Description
point	Type: StatusLogLocation
status	Type: string The current order status. Possible values: new — The order was created. confirmed — The order delivery time was set (confirmed with recipient). finished — The order was delivered. partially_finished — The order was delivered only partially. Order status can be set to `partially_finished` only for companies with `company.partially_finished_status_enabled` flag equals `true`. cancelled — The order was canceled. postponed — The order is postponed or the courier couldn't contact the customer.
timestamp	Type: number<float> The time when changes were made (UNIX timestamp).

OrderGetWithNotificatons_time_window

Allowed time window to visit location, in ISO 8601 format.

Name

Description

end

Type: string<datetime>

Example: Wed Mar 06 2019 17:16:30 GMT+0300 (Moscow Standard Time)

start

Type: string<datetime>

Example: Wed Mar 06 2019 17:15:00 GMT+0300 (Moscow Standard Time)

OrderHistoryPosition

Courier position. Appears only in events ARRIVAL, ORDER_VISIT, DEPARTURE.

Name	Description
lat	Type: number<float> Courier position latitude.
lon	Type: number<float> Courier position longitude.
time	Type: string<datetime> The client time of the event in ISO 8601 format.

OrderStatusUpdateSource

Source of the event. Appears only in event STATUS_UPDATE.

Name

Description

initiator

Type: string

Initiator of the event, possible values: yandex, app, user_api.

StatusLogLocation

Name

Description

lat

Type: number<float>

Latitude of the point where changes were made.

lon

Type: number<float>

Longitude of the point where changes were made.

401 Unauthorized

Deprecated

Authorization error. Make sure that the request header contains the correct OAuth token.

422 Unprocessable Entity

Deprecated

Incorrect input. The operation can't be performed.

504 Gateway Timeout

Deprecated

Error working with the API. Repeat the request.

Adds an order

Request

Path parameters

Body

OrderNotification

Responses

200 OK

Body

OrderHistoryItem

OrderStatusUpdateComment

CompanyNumber

StatusLog

OrderGetWithNotificatons_time_window

OrderHistoryPosition

OrderStatusUpdateSource

StatusLogLocation

401 Unauthorized

422 Unprocessable Entity

504 Gateway Timeout

Was the article helpful?