Create Order (Task)

Use to create an order (task). The Create Order service is the Bringg Service you can use to create the “unit of action” connecting the company, the driver, and the customer. An order describes the general or meta information for each "unit of action" request. The Create Order service, also called Create Task, supports various use cases by combining the attributes and objects described below for robust order creation including:

  • single pickup and delivery
  • a multi pickup and delivery combination
  • long routes.

An order includes:

  • A customer - the owner of the order. The customer can view all stops in the order and is frequently the last stop in the order. For information about the customer object, see Customer Object.
  • A user - the driver associated with the order.
  • Order pricing, scheduling, geoposition latitude and longitude, and notes, as well as other feature details associated with orders.
  • A waypoint or way points - either one or a maximum of two destinations in a single order which may be a pickup, drop-off, or visit. For information about the way point object, see Way Point Object. Each way point can including the following:
    • Customer (order owner) details - if the customer attributes for a way point differ from the customer attributes for the order or the other way points, the way point object includes a customer object with those details.
    • Customer details - information about the customer at each way point, including name, address, and expected times, as well as additional, optional information. Customer details are customer objects contained in way point objects.
    • Inventory - items to collect or delivery at each way point, for example parcels, food, and menu items. For information about the inventory object, see Inventory Object.
    • Rules - delivery rules for each way point, if rules exist. Rules are also inherited from tags or other configurations.

The Create Order service requires a customer. The customer can be either an existing customer or a new customer. To create an order for an existing customer, use the Bringg Customer Id. The details of the existing customer will appear on the order. To create an order for a new customer, use the Customer object and include the new customer's details. Additionally, you can include a customer in each way point.

NOTE: Some order details are associated with the entire order while other details are associated with individual way points or customers at individual way points. For example, the payment method is associated with the order and is an attribute of the Create Order service. On the other hand, the delivery confirmation options are associated with individual way points and is an attribute of way point objects within the order.

Time horizon
Date & Time values must fall within a 10-year range.
In case a call fails due to date validation, a corresponding response will be generated
{
"success": false,
"message": "One of the parameters is incorrect: [Time '+92022-02-01T00:00:00Z' is out of range '10 years' for 'no_earlier_than']"
}

❗️

Up to two destinations per order

From May 2022 all Bringg orders can only have a either one or two destinations (waypoints). A single order cannot have more than two destinations.

OUTPUT PARAMS

success

boolean

Indicates whether the service completed successfully.

  • false - the service failed.
  • true - the service succeeded.

rc

Int32

If an error occurred, the return code.

message

string

If an error occurred, a message indicating the error.

id

Int32

The unique Id of this order.

active_way_point_id

Int32

The Id of the way point in this order that is the user's (driver's) next destination.

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.

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

Object

An object containing detailed information about the customer associated with this order, see Customer.

customer_id

Int32

The Id of the customer associated with this order.

external_id

string

The order's external Id.

fleet_id

Int32

If this order is assigned to an external fleet, this is the Id of that external fleet.

late

Int32

Indicates whether the user (driver) has not arrived at way points in this order on or before the scheduled times. The values are:

  • false or 0 - the user (driver) is not late
  • true or 1 - the user (driver) is late

The default value is false.

merchant_id

Int32

The Id of the company. The merchant_id may be null, if the developer works with only one company.

priority

Int32

The priority of this order.

ready_to_execute

Int32

Indicates whether this task is in planning phase or has been dispatched to drivers. The values are:

  • false or 0 - Task appears in Planning tab and is not visible to users (drivers)
  • true or 1 - Task appears in Dispatch tab and is visible to users (drivers).

status

Int32

This order's status. The values are:

  • 0 - created
  • 1 - assigned
  • 2 - on_the_way
  • 3 - checked_in
  • 4 - done
  • 5 - this status is not in use
  • 6 - accepted
  • 7 - canceled
  • 8 - rejected
  • 9 - unacknowledged

The Order Created callback returns the value 0 (created).

scheduled_at

datetime

The date and time this order was scheduled. This is in UTC and is in the format is " %Y-%m-%dT%H:%M:%S%z".

tag_id

Int32

If a tag exists, this is the Bringg tag Id.

task_inventories

Array of Objects

An array of objects containing this order's inventory, see Task Inventories.

task_notes

Array of Objects

An array of objects containing notes added to this order, see Task Notes.

team_ids

Array of Int32

An array of Int32 containing the Ids of all teams assigned to this order.

tip_driver_enabled

Int32

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.

updated_at

datetime

The date and time of the last update for this order. This is in UTC and is in the format is " %Y-%m-%dT%H:%M:%S%z".

user_id

Int32

The Id of the user (driver). The default value is null, if no user (driver) is assigned.

uuid

Int32

The universal unique Id of this order.

way_points

Array of Objects

An array of of one or (at most) two objects containing way_point information. See Way Point.

extras

json

The field "extras" in Bringg is used to store metadata in a JSON format of field & value.
Data sent in the "extras" field will not be used/exposed in Bringg applications. It can be retrieved back from our webhooks.
The field is available for the following levels: Task, WayPoint, Customer & TaskInventories.

curl -H "Content-Type: application/json" -X POST -d '{"title": "Generic Title", "external_id": "ABC15D", "customer": {"name": "Mr. Customer", "company_id": XXX, "address": "1 Wall st, New York, NY", "phone": "0545674815"}}' https://admin-api.bringg.com/services/6f15901b/b7012168-c9b6-4c64-9aeb-4272a345dbb0/54efd3d9-d3ed-4e53-8a44-039ade4305b0/
Language