API Reference

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.

For example, after creating a service plan in the Bringg UI or with the Create Service Plan endpoint, use the service_plan_external_id parameter when creating orders instead of mapping and sending tag_id and task_configuration_id.

ParameterDescriptionValidations and Notes
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_tasks
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.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.
Read more about the Customer Object.
delivery_cost
double		The cost per delivery charged by a third-party carrier.
delivery_price
double		The delivery fee 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.
external_fleet_id
string		Your external system's ID for the carrier assigned to this order.Omit or leave this parameter null to manually or automatically assign the order in Bringg.
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. For example:
{"field":"value"}
has_parking_area
boolean		Indicates whether there is a loading/unloading zone at the destination.
left_to_be_paid
double		The unpaid balance of this order.
notes
array		An array of notes associated with the order. Each note should include the note and note_creator parameters. This creates a task_note object.For example:
"notes": [
{
"note": "Note by customer",
"note_creator": "customer"
},
{
"note": "System note via integration",
"note_creator": "user"
}
]
Read more about the Order Notes Object .
note_creator
string		The name to use as the creator of the note.Possible values:
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
double		The net price of this order (not including taxes).-
priority
integer		Priority of the order within an 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.Learn more about the Quotes object.
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 order is in planning phase or has been dispatched to drivers.Possible values:
false or 0- the order appears in the Planning tab and is not visible to drivers
trueor1 - the order 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".Learn more about setting up skills in Bringg.
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
double		A fee applied when the customer's order subtotal does not meet the "small cart" threshold.\When updating a leg of a linked order using the order's external_id, use this field to indicate which leg.-
task_type_id
integer		Indicates the order type. Can also be automatically generated when inventory or waypoint objects indicate the order type.When updating a leg of a linked order using the order's external_id, use this field to indicate which leg.
Possible values:
2: Pickup
3: Return
4: Dropoff
5: Pickup and dropoff
tax_price
double		The total tax amount charged for the order.
external_team_id
string		The selected team's ID in your external systems.Include external_team_id or team_id to automatically assign an order to a specific team.
tip
double		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. When omitted, Bringg calculates the aggregated handling_units from the inventory object.
total_price
double		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, such as when created as part of an unconfirmed quote.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. Read more about the Way Point Object.Required

Response and Webhook Data

Below is a list of the data returned in webhooks and responses to your API requests. The inclusion of specific parameters may depend on your use case, your API request, and the webhook fields you have subscribed to.

ParameterDescription
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".
customer_id
integer		Bringg's ID of the customer associated with this order.
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_price
float		The delivery fee charged by you to your end customer.
delivery_window_id
integer		Bringg's ID for the delivery window selected by or assigned to the customer.
discount
float
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_id
string		Your external system's ID for this order.
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
left_to_be_paid
double		The unpaid balance of this total order.
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.
merchant_id
integer		The ID of the merchant to which the order belongs.
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.
payment_type_name
string		The name of the payment type. For example, Visa, Mastercard, or Amex.
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
double		The tip (gratuity) paid to the driver in cash after delivery.
post_delivery_tip_credit
double		The tip (gratuity) paid to the driver by credit after delivery.
pre_delivery_tip
double		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
price_before_tax
double		The net price of this order not including taxes.
priority
integer		Sequence of the order within an assigned route. For example, Priority 1 is the first stop in the route.
ready_to_execute
boolean		Indicates whether this order is in planning and not visible to users (drivers). The values are:
false or 0 - is not in planning and is visible to users (drivers)
true or 1 - is in planning and is not visible to users (drivers)
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_start_time
datetime		If the order is part of a "run", this is the start date and time of the "run". A "run" is a group of user (driver) tasks beginning at the time a user (driver) leaves a "base" and ending when the user (driver) returns to that "base".
This is in UTC and is in the format " %Y-%m-%dT%H:%M:%S%z".
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_at
datetime		The date and time this order was scheduled. This is in UTC and is in the format " %Y-%m-%dT%H:%M:%S%z".
scheduled_to_be_ready
datetime		The date and time when an order is scheduled to be ready for pickup from a waypoint.
service_fee
double		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. This is in UTC and is in the format " %Y-%m-%dT%H:%M:%S%z".
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
external_carrier_tracking_url >
string 		The carrier's tracking link.
Included as part of the task_fleet_mapping > shared_extras objects, which contain information provided by the carrier associated with this order and can be included in flexible webhooks.
tag_id
integer		The Bringg ID of the tag associated with this order.
tax_price
float		The tax amount of the price of this order.
tip
float		The tip (gratuity) paid to the driver for this order.
tip_driver_enabled
boolean		Indicates whether the user (driver) is allowed to be tipped. The values are:
false or 0 - the user (driver) cannot be tipped
true or 1 - the user (driver can be tipped
title
string		This order's title. The maximum length is 255 characters.
total_price
float		The total price of this order.
updated_at
datetime		The date and time of the last update for this order. This is in UTC and is in the format " %Y-%m-%dT%H:%M:%S%z".
user_id
integer		Bringg's ID for the driver associated with this order.
uuid
uuid		A universally unique identifier (UUID) for this order.
way_points
array of objects		The list of waypoints associated with this order. For more details, see the Way Point Object.