Order (Task) Object

The order object is included in many webhook callbacks and contains all available values related to an order in Bringg.

Order Details

To create or update orders in Bringg, it's important to understand the different parameters that you can use in your payloads. Not all parameters are relevant for each order, so be sure to only include those that are relevant for your use organization. For example, if you wish to assign an order to your own fleet or for an order to be assigned once it is already in Bringg, do not include fleet_id in your payload.

Below is a list of all available parameters. If there are parameters that you want to include but are not listed here, you can create custom attributes that can be displayed and used throughout Bringg.

📘

Best practice

We recommend using external IDs, which you define, in your requests. This reduces the need for you to map entities that already exist in your other systems.

FieldDescriptionValidations and Notes
cancellation_lat
double
The driver's geographical latitude when canceling the task.
cancellation_lng
double
The driver's geographical longitude when canceling the task.
create_group
boolean
Indicates whether to automatically group this order with other orders that have the same customer or grouping key.Possible values:
false or 0 - do not group order
true or 1 - group order
create_linked_task
boolean
When both the pickup and dropoff location for an order are destinations on a route (neither are located at the route origin), true creates two linked orders for individual optimization.To create linked tasks, send your payload as a task object. For example:

{"task":{ "external_id":"1", "create_linked_tasks":true, "way_points":[] }} |
customer
object
An object containing detailed information about a new customer to create and associate with this order. Read more about the Customer Object.To attach an order to an existing customer, include their external_id in the customer object. You can configure additional identifying attributes in the Bringg platform under Settings > Merchant Configuration > Dispatch Behavior > Unique customer ID.
delivery_price
float
The delivery cost that the customer pays at checkout.
discount
double
The discount applied to this order at checkout.
external_id
string
The order's ID in your external systems.Maximum 255 characters
external_fleet_id
string
Your external system's ID for the carrier assigned to this order.Omit this parameter to manually or automatically assign a carrier within Bringg.
external_team_id
string
Your external system's ID for the selected team.Include external_team_id to automatically assign an order to a specific team.
external_user_id
string
Your external system's ID for the driver associated with this order.
extras
json
This field can be used to send custom attributes to Bringg.JSON format of field and value
has_parking_area
boolean
Indicates whether there is a loading/unloading zone at the destination.
left_to_be_paid
float
The unpaid balance of this order.
left_to_be_paid_for_delivery
float
The unpaid balance for delivery of this order.
notes
array
An array of notes associated with the order. Each note should include the note and note_creatorparameters. This creates a task_note object.
Read more about the Order Notes Object.

Possible values for note_creator:
customer - logs the waypoint customer as the note creator
user- logs the driver as the note creator
payment_method
integer
The payment method for this order.Possible values:
0: unknown, 1: cash, 2: credit, 3: check, 4: credit card terminal
payment_type_name
string
The name of the payment type, used to specify which payment equipment is required for this order.
price_before_tax
float
The net price of this order (not including taxes).
priority
integer
Priority of the order within assigned route. For example, Priority 1 is the first stop in the route.Should be used when orders are assigned to a route before being sent to Bringg.
quote_id
integer
The ID of a quote received as a response from the Get Quotes request and selected for use in your external systems, such as customer checkout.
rank
integer
Defines the priority of a customer or order when using Route Optimization or AutoDispatch.null is the lowest rank, 1 is the highest, 2 is the second highest, and so on.
0 is not accepted.
ready_to_execute
boolean
Indicates whether this task is in the planning phase or has been dispatched to drivers. Possible values:
false or 0 - the task appears in the Planning tab and is not visible to drivers.
true or 1 - the task appears in the Dispatch tab and is visible to drivers.
required_skills
array of strings
An array of driver skills or vehicle capabilities required to carry out this order, such as "fridge installation".
service_plan_external_id
string
The ID in your system for the Service Plan applied to this order.Service Plans are used to set SLA and driver actions.
small_cart_fee
float
A fee applied when the customer's order subtotal does not meet the "small cart" threshold.
task_type_id
integer
Indicates the order type. Can also be automatically generated when inventory or waypoint objects indicate the order type.Possible values:
2: Pickup
3: Return (indicates that the driver is returning to the team location)
4: Dropoff
5: Pickup and dropoff
tax_price
float
The total tax amount charged for the order.
tip
float
The tip (gratuity) paid to the driver by the customer for this order.
tip_driver_enabled
boolean
Indicates whether the driver can be tipped for this order.Possible values:
false or 0- the driver cannot be tipped
true or 1 - the driver can be tipped
title
string
The order's title.Maximum 255 characters
total_handling_units
string
Use to ensure that the vehicle does not exceed capacity even if a customer adds last-minute items to their order.
total_price
float
The total price of this order.
total_weight
integer
Use to ensure order does not exceed vehicle capacity even if customers add last-minute items to their order. Bringg calculates according to the higher value, total_weight or the aggregated weight of all inventory items in the order.
vehicle
object
The vehicle associated with this order.
virtual_task
boolean
Indicates if an order should be scheduled by the customer or a dispatcher.Possible values:
false or 0 - not a virtual order. This is the default value.
true - this order should be scheduled by a customer or dispatcher.
way_points
object
An array of one or two objects containing destination information.Required

Response and Webhook Data

The response data returned with API responses and webhooks, in addition to parameters from the order details parameters above. The inclusion of specific parameters depends on the request or webhook fields you have subscribed to.

FieldDescription
success
boolean
Indicates whether the service completed successfully.

false - the service failed.
true - the service succeeded
message
string
If an error occurred, a message indicating the error is included.
rc
integer
If an error occurred, the return code is included.
accept_time
datetime
The date and time when the driver accepted this order.
acknowledged_at
datetime
The time at which the order was acknowledged by a dispatcher. If orders are auto-acknowledged, then this time is set upon creation.
active_way_point_id
integer
The ID for the incomplete waypoint associated with this order.
automatically_assigned
boolean
Indicates whether this order was automatically assigned. The values are:
false or 0 - this order was not automatically assigned
true or 1 - this order was automatically assigned.
automatically_cancelled
integer
Indicates the method used to cancel this order. Possible values:
0 - manually using the Driver App
1 - automatic check-in or check-out via geofence
2 - driver's action when prompted by the Driver App
3 - from linked task
4 - updated via the Cancel Order API request
5 - updated by the carrier
6 - automated by activity trigger
7 - updated using the Bringg platform
8 - updated using the store app
9 - updated from Run End
10 - automatic by server
automatically_ended
integer
Indicates the method used to end this order. Possible values:
0 - manually using the Driver App)
1 - automatic check-in or check-out via geofence
2 - driver's action when prompted by the Driver App
3 - from linked task
4 - updated via the Cancel Order API request
5 - updated by the carrier
6 - automated by activity trigger
7 - updated from a child task
8 - from the store app
9 - from run end
10 - updated by Bringg automation
11- updated via API
automatically_started
integer
Indicates the method used to start this order. Possible values:
0 - manually using the Driver App
1 - automatic check-in or check-out via geofence
2 - driver's action when prompted by the Driver App
4 - auto_corrected_by_client
5 - auto_corrected_by_server
6 - automated by activity trigger
7 - updated in the Bringg platform
8 - updated in the store app
9 - from_run_end
10 - updated by Bringg automation
cancelled_at
datetime
The date and time when this order was canceled.
created_at
datetime
The date and time this order was created. This is in UTC and is in the format is "%Y-%m-%dT%H:%M:%S%z".
delete_at
datetime
A null timestamp indicates that the entity is still active or present in Bringg.
delivery_cost
float
The delivery fee charged by a third-party carrier.
delivery_window_id
integer
Bringg's ID for the delivery window selected by or assigned to the customer.
dispatcher_id
integer
The ID of the dispatcher who assigned this order.
distance_automatically_set
integer
Indicates how the distance_traveled for this order was calculated. Possible values:
0 - automatic
1 - estimated
2 - manual
distance_traveled
double
The actual distance traveled (in km).
driver_payments
Array
An array including details of all payments accepted by a driver for this order.
ended_time
datetime
The date and time when the order was canceled or marked as complete.
external_user_id
string
Your external system's ID for the driver associated with this order.
failed_delivery_attempts
integer
The number of times a driver unsuccessfully attempted to deliver the order.
fleet
object
An object containing the details of an assigned or quoted fleet.
fleet_delivery_external_id
string
The external carrier's ID for the order.
fleet_id
integer
Bringg's ID for the external carrier.
group_leader_id
integer
If this order is part of a group of orders, this is the ID of the order representing the entire collection of orders in the group (the parent order containing all child orders in the group). This is the ID that Bringg operators (for example, dispatchers and users/drivers) view. NOTE: Bringg internally maintains each order and each order contains the same group leader ID.
group_uuid
string
If this order is a group of orders, this is the UUID of the group (see group_leader_id).
id
integer
The unique ID of this order in Bringg.
invalidated
boolean
When true, signifies that this order is missing fields that Bringg requires to validate orders and include them in order lists and optimization among other Bringg features.
last_assigned_time
datetime
The last date and time this order was assigned to a driver.
last_ready_to_execute_at
datetime
The last time this order was marked as ready to execute.
last_way_point_lat
double
The geographical latitude for the last waypoint for the order.
last_way_point_lng
double
The geographical longitude of the last waypoint for the order.
late
boolean
Indicates whether the driver has not arrived at a destination in this order on or before the scheduled times. The values are:
false or 0 - the driver is not late
true or 1 - the driver is late
The default value is false.
late_reason
string
linked_task_id
integer
Bringg’s ID for a linked order. Linked orders are created when one order is split into distinct tasks for each waypoint.
parent_task_id
integer
If this order was created from another order (for example, one that failed), this is the ID of the original order.
planned_distance_from_prev_task
double
The distance to this order's last waypoint from the last waypoint of the preceding order in the route, as calculated during Route Optimization and via manual planning adjustments in the route planner.
planning_done
boolean
Indicates if this order has been organized into a route, and that route has been marked as "Done Planning."
planning_published
boolean
Indicates if the planned delivery window has been finalized or shared with the customer.
post_delivery_tip_cash
float
The tip (gratuity) paid to the driver in cash after delivery.
post_delivery_tip_credit
float
The tip (gratuity) paid to the driver by credit after delivery.
pre_delivery_tip
float
The tip (gratuity) paid to the driver before delivery.
preparation_acknowledge
_time_actual

datetime
Time and date when the order was actually acknowledged.
preparation_end
_time_actual

datetime
Time and date when the order actually ended.
preparation_end
_time_planned

datetime
Time and date when the order was scheduled to end.
preparation_picked_up_
time_actual

datetime
Time and date when the order was actually picked up.
preparation_ready_for_
pickup_time_actual

datetime
Time and date when the order was actually ready for pick up.
preparation_ready_for
_pickup_time_planned

datetime
Time and date when the order was scheduled to be ready for pickup.
preparation_start_
time_actual

datetime
Time and date when preparation of the order actually began.
preparation_start_
time_planned

datetime
Time and date when preparation of the order was scheduled to begin.
preparation_status
integer
The order's stage in the preparation workflow. Possible values:
0- acknowledged
1- preparation started
2- preparation ended
3- ready for pickup
4- picked up
5- send to preparation failed
recurrent_task_template_id
integer
Designates the recurring order series that generated this order. See Create Recurring Order Template.
reserved_until
datetime
Date and time when the reservation of a delivery slot for an order expires. If the order is not completed by this time, the delivery slot reservation expires and the order is canceled.
run_id
integer
The ID of the route the order is assigned to.
run_uuid
uuid
The UUID of the run the order is assigned to. Use run_id to search in Bringg UI.
scans
array of objects
An array of objects including details about barcode scans related to an order, such as for inventory items.
scheduled_to_be_ready
datetime
The date and time when an order is scheduled to be ready for pickup from a waypoint.
service_fee
float
The service fee charged by an external carrier. Usually calculated as a percentage of the subtotal of the order.
service_plan_id
integer
Bringg's ID for the Service Plan applied to this order. Service Plans are used to set SLA and driver actions.
shared_locations
array of objects
Array of objects that includes URLs, tokens, and identifying data related to the customer experience for a waypoint.
shift_id
integer
Bringg's ID for the driver's shift when fulfilling this order.
start_lat
double
The geoposition latitude of the driver when this order started.
start_lng
double
The geoposition longitude of the driver when this order started.
started_time
datetime
The date and time when the driver started this order.
status
string
Indicates the current status of this order. Possible values include:
0- new
1 - assigned
2 - on the way
3 - checked in
4- done
6 - accepted
7- canceled
8 - rejected
9 - unacknowledged
tip
float
The tip (gratuity) paid for this order.
updated_at
datetime
The last time this order's details were updated.
way_points
array of objects
The list of waypoints associated with this order. For more details, see the Way Point Object.
uuid
uuid
A universally unique identifier (UUID) for this order.