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.
Field | Description | Validations 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_creator parameters. 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. Learn more about the Way Point Object. | 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.
Field | Description |
---|---|
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 App1 - automatic check-in or check-out via geofence2 - driver's action when prompted by the Driver App3 - from linked task4 - updated via the Cancel Order API request5 - updated by the carrier6 - automated by activity trigger7 - updated using the Bringg platform8 - updated using the store app9 - updated from Run End10 - 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 geofence2 - driver's action when prompted by the Driver App3 - from linked task4 - updated via the Cancel Order API request5 - updated by the carrier6 - automated by activity trigger7 - updated from a child task8 - from the store app9 - from run end10 - updated by Bringg automation11 - updated via API |
automatically_started integer | Indicates the method used to start this order. Possible values:0 - manually using the Driver App1 - automatic check-in or check-out via geofence2 - driver's action when prompted by the Driver App4 - auto_corrected_by_client5 - auto_corrected_by_server6 - automated by activity trigger7 - updated in the Bringg platform8 - updated in the store app9 - from_run_end10 - 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 - automatic1 - estimated2 - 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 latetrue or 1 - the driver is lateThe 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 up5 - 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. |