Create Order (Task)

The Create Order endpoint allows you to create an order (also known as a task) in Bringg. This API service supports various use cases and workflows.

The Order (Task) Object can include a wide variety of attributes, including the following components:

Customer: the recipient of the goods or services provided by this order. The customer's address is often the second waypoint in the order. Visit the Customer Object to learn more.
User: the driver associated with the order. The driver can be assigned when creating an order but is often assigned automatically or manually once the order is created in Bringg. Read more about the User Object.
Waypoints: One or two waypoints, each of which can be a pickup, drop-off, or visit. Each waypoint can include specific customer and inventory details as well as requirements such as the handoff policies. For information about the waypoint object, see Way Point Object.

NOTE: Some order details are associated with the entire order, while other details are associated with individual waypoints or customers at individual waypoints. For example, the payment method is associated with the order and is an attribute of the Create Order service. On the other hand, the notes options are associated with individual waypoints and are attributes of waypoint objects within the order.

Potential Errors

Error Code	Error Message	Resolution
`200`	`Quote expired`	The `quote_id` has expired. Obtain a new quote ID and try again.
`200`	`One of the parameters is incorrect: [Time '+92022-02-01T00:00:00Z' is out of range '10 years' for 'no_earlier_than']`	Make sure that date and time values fall within a 10-year range.
`200`	`Task with external id [ID] exists already`	There is already an order with this external ID. Send Update Task or check the external ID and try again.
`400`	`An order can not include more than 2 way points. Please remove additional destinations.`	Remove extra waypoints and try again.
`200`	`No service_plan with id <ID> found`	Check the service plan ID in the Settings > Service Plans and try again.
`200`	`reserved_until cannot be in the past`	Update the `reserved_until` timestamp and try again. Check your external systems to understand why this timestamp was sent.
`200`	`Task with uuid [id] exists already.`	There is already an order with this Bringg ID. Send Update Task to update the order instead.
`200`	`The max allowed inventory per task is passed the limit. Reach your account manger for more information.`	Reach out to your account manager for more information.
`200`	Teams [team IDs] not found.	Check the team IDs: - Go to Resources > Teams, or - Send the Show All Teams API request.
`200`	`Customer [customer_id] does not exist.`	Check the customer ID in Customers or create a new customer by including the `customer` object.
`200`	`Customer [customer_id] is out of range.`
`200`	`Driver with external_id [user_external_id] was not found` or `Driver with id [user_id] was not found`	Check the driver's ID: - Go to Resources > Drivers, or - Send the Get Users API request.
`200`	`Driver can't access to the team id [team_id]`	Check which team the driver is assigned to: - Go to Resources > Drivers and select the driver's name, or - Send the Get User API request.

Response (Output) Params

This list of output parameters includes all of the fields that Bringg adds to an order once it is received. For more details, including a table of body params, see the Order (Task) Object.

Parameter	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 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.