API Reference

Delivery Created Webhook

When you receive this webhook, create the delivery in your system using the data contained in the webhook.

NOTE: Nested inventory is supported (parent-child).

📘

What we expect from you in response

  • If you are able to do the delivery, return a success:true along with your Delivery ID.
  • Please make sure to send a 200 Success code (not 201).
  • If you are not able to do the delivery (want to reject it), then send success:false and a reason (error_message) for the rejection.
  • Please send a 200 code even in response to a rejection.

❗️

Timeout

Bringg expects a response within 30 seconds. After 30 seconds with no response, this will be considered a timeout. Bringg will retry the webhook 3 times.

🚧

Number of Waypoints / Stops

There will ALWAYS be 2 waypoints or stops in the webhook payload : Pickup and Dropoff.

{
	"success": true,
	"delivery_id": "ABCD1234",
    "delivery_cost": 1050,
    "green_delivery": true,
    "fleet_extras": {
      "some": "important info"
    }
}
{
	"success": false,
	"error_message": "No drivers working that day"
}

🚧

Mandatory fields in the Success True response

There are only 2 mandatory fields that you need to include in Success True response:

  • "success": true
  • "delivery_id" : "< YOUR DELIVERY ID >"

SUCCESS:TRUE RESPONSE PARAMS

*success

boolean

Value must be 'true'. MANDATORY

*delivery_id

string

The ID of the delivery in YOUR system. It allows your delivery to be mapped to the order in Bringg's system. It is a **string** field, so it needs to be enclosed in quotation marks (as in the example above). MANDATORY
NOTE: We include your Delivery ID in the Delivery Updated and Delivery Cancelled webhooks in order to make it easier for you to identify for which order in your system the webhook applies.

delivery_cost

float

The fee that you are charging for delivery of this order, in currency of cents. For example: 560 and NOT 5.60. OPTIONAL

green_delivery

boolean

Allows you to indicate whether a green vehicle will be delivering this order. OPTIONAL

fleet_extras

JSON

Custom information that needs to be shared with Bringg. OPTIONAL

EXAMPLE PAYLOAD

🚧

Save the "id" value

Make sure to save down the "id" value into your system as the Bringg Order ID. You will need to use this as the "task_id" value when you send API calls to Bringg.

{
   "id": 11798477,
   "title": "Order Title",
   "external_id": "1595332836",
   "extras": {
      "services": {
         "external_id": "3",
         "name": "CARRYING_INTO_CUSTOMER_HOME"
      }
   },
   "priority": 11798477,
   "run_id": null,
   "service_plan_id": null,
   "task_configuration_id": null,
   "price_before_tax": 20.82,
   "left_to_be_paid": null,
   "total_price": null,
   "tag_id": 278,
   "pre_delivery_tip": null,
   "tip": null,
   "required_skills": [],
   "preparation_external_id": null,
   "type": "delivery",
   "way_points": [
      {
         "id": 17352991,
         "position": 1,
         "pickup_dropoff_option": "pickup",
         "scheduled_at": "2021-07-21T13:00:00.000Z",
         "asap": null,
         "no_later_than": "2021-07-21T18:00:00.000Z",
         "no_earlier_than": "2021-07-21T08:00:00.000Z",
         "extras": null,
         "first_attempt_promise_no_later_than": null,
         "first_attempt_promise_no_earlier_than": null,
         "address": "5210 Trademark Drive, Raleigh, NC",
         "address_second_line": "1st floor",
         "zipcode": "27610",
         "address_type": null,
         "borough": null,
         "city": "Raleigh",
         "state": null,
         "house_number": null,
         "district": null,
         "lat": 40.544927,
         "lng": -3.614623,
         "customer": {
            "id": 9351755,
            "external_id": "B84818444",
            "name": "Warehouse Name / Store Name",
            "email": null,
            "phone": null,
            "allow_sending_email": true,
            "allow_sending_sms": true,
            "language": null,
            "extras": null
         },
         "inventory": [
            {
               "services": [],
               "id": 42756814,
               "original_quantity": 1,
               "scan_string": "016893799",
               "name": "Package",
               "external_id": "17476748",
               "age_restricted": null,
               "price": null,
               "extras": null,
               "image": "https://site.com/images/product-placeholder.png",
               "weight": 32,
               "width": 42,
               "height": 76,
               "length": null,
               "volume": null,
               "size": null,
               "inventory": [
                  {
                     "services": [],
                     "id": 42756815,
                     "original_quantity": 1,
                     "scan_string": "8213672",
                     "name": "Fridge",
                     "external_id": "82136703",
                     "age_restricted": null,
                     "price": 2.52,
                     "extras": null,
                     "image": "https://site.com/images/product-placeholder.png",
                     "weight": 32,
                     "width": 42,
                     "height": 76,
                     "length": null,
                     "volume": null,
                     "size": null
                  }
               ]
            }
         ],
         "notes": []
      },
      {
         "id": 17352992,
         "position": 2,
         "pickup_dropoff_option": "dropoff",
         "scheduled_at": null,
         "asap": null,
         "no_later_than": "2021-07-21T19:00:00.000Z",
         "no_earlier_than": "2021-07-21T08:00:00.000Z",
         "extras": null,
         "first_attempt_promise_no_later_than": null,
         "first_attempt_promise_no_earlier_than": null,
         "address": "6305 Lake Wheeler Road",
         "address_second_line": null,
         "zipcode": "27603",
         "address_type": null,
         "borough": null,
         "city": "Raleigh",
         "state": "NC",
         "house_number": null,
         "district": null,
         "lat": 40.5462107,
         "lng": -3.6291206,
         "customer": {
            "id": 9351756,
            "external_id": "9351756",
            "name": "Susan Martin",
            "email": "",
            "phone": null,
            "allow_sending_email": false,
            "allow_sending_sms": true,
            "language": null,
            "extras": null
         },
         "inventory": [
            {
               "services": [],
               "id": 42756814,
               "original_quantity": 1,
               "scan_string": "016893799",
               "name": "Package",
               "external_id": "17476748",
               "age_restricted": null,
               "price": null,
               "extras": null,
               "image": "https://site.com/images/product-placeholder.png",
               "weight": 32,
               "width": 42,
               "height": 76,
               "length": null,
               "volume": null,
               "size": null,
               "inventory": [
                  {
                     "services": [],
                     "id": 42756815,
                     "original_quantity": 1,
                     "scan_string": "8213672",
                     "name": "Fridge",
                     "external_id": "82136703",
                     "age_restricted": null,
                     "price": 2.52,
                     "extras": null,
                     "image": "https://site.com/images/product-placeholder.png",
                     "weight": 32,
                     "width": 42,
                     "height": 76
                  }
               ]
            }
         ],
         "notes": [
            {
               "id": 18673468,
               "external_id": "18673468",
               "note": "Note 3"
            },
            {
               "id": 18673467,
               "external_id": "18673467",
               "note": "Note 2"
            },
            {
               "id": 18673466,
               "external_id": "18673466",
               "note": "Note 1"
            }
         ]
      }
   ],
   "packages": [],
   "team": {
      "name": "Central Store",
      "external_id": "ABC123"
   },
   "customer": {
      "id": 9351754,
      "external_id": "9351754",
      "name": "Susan Martin",
      "email": "",
      "phone": null
   },
   "service_plan": {
      "service_plan_id": 63,
      "service_plan_name": "DIY",
      "service_plan_external_id": "DIY"
   },
   "preparation_status_id": 0,
   "preparation_status": "ACKNOWLEDGED",
   "request_id": "b42493e2-d7f0-41e6-87aa-38294d336917",
   "quote_id": null   
  ]
}
{
   "id": 11798477,
   "title": "Order Title",
   "external_id": "1595332836",
   "extras": {
      "services": {
         "external_id": "3",
         "name": "CARRYING_INTO_CUSTOMER_HOME"
      }
   },
   "priority": 11798477,
   "run_id": null,
   "service_plan_id": null,
   "task_configuration_id": null,
   "price_before_tax": 20.82,
   "left_to_be_paid": null,
   "total_price": null,
   "tag_id": 278,
   "pre_delivery_tip": null,
   "tip": null,
   "required_skills": [],
   "preparation_external_id": null,
   "type": "delivery",
   "way_points": [
      {
         "id": 17352991,
         "position": 1,
         "pickup_dropoff_option": "pickup",
         "scheduled_at": "2021-07-21T13:00:00.000Z",
         "asap": null,
         "no_later_than": "2021-07-21T18:00:00.000Z",
         "no_earlier_than": "2021-07-21T08:00:00.000Z",
         "extras": null,
         "first_attempt_promise_no_later_than": null,
         "first_attempt_promise_no_earlier_than": null,
         "address": "5210 Trademark Drive, Raleigh, NC",
         "address_second_line": "1st floor",
         "zipcode": "27610",
         "address_type": null,
         "borough": null,
         "city": "Raleigh",
         "state": null,
         "house_number": null,
         "district": null,
         "lat": 40.544927,
         "lng": -3.614623,
         "customer": {
            "id": 9351755,
            "external_id": "B84818444",
            "name": "Warehouse Name / Store Name",
            "email": null,
            "phone": null,
            "allow_sending_email": true,
            "allow_sending_sms": true,
            "language": null,
            "extras": null
         },
         "inventory": [
            {
               "services": [],
               "id": 42756814,
               "original_quantity": 1,
               "scan_string": "016893799",
               "name": "Package",
               "external_id": "17476748",
               "age_restricted": null,
               "price": null,
               "extras": null,
               "image": "https://site.com/images/product-placeholder.png",
               "weight": 32,
               "width": 42,
               "height": 76,
               "length": null,
               "volume": null,
               "size": null,
               "inventory": [
                  {
                     "services": [],
                     "id": 42756815,
                     "original_quantity": 1,
                     "scan_string": "8213672",
                     "name": "Fridge",
                     "external_id": "82136703",
                     "age_restricted": null,
                     "price": 2.52,
                     "extras": null,
                     "image": "https://site.com/images/product-placeholder.png",
                     "weight": 32,
                     "width": 42,
                     "height": 76,
                     "length": null,
                     "volume": null,
                     "size": null
                  }
               ]
            }
         ],
         "notes": []
      },
      {
         "id": 17352992,
         "position": 2,
         "pickup_dropoff_option": "dropoff",
         "scheduled_at": null,
         "asap": null,
         "no_later_than": "2021-07-21T19:00:00.000Z",
         "no_earlier_than": "2021-07-21T08:00:00.000Z",
         "extras": null,
         "first_attempt_promise_no_later_than": null,
         "first_attempt_promise_no_earlier_than": null,
         "address": "6305 Lake Wheeler Road",
         "address_second_line": null,
         "zipcode": "27603",
         "address_type": null,
         "borough": null,
         "city": "Raleigh",
         "state": "NC",
         "house_number": null,
         "district": null,
         "lat": 40.5462107,
         "lng": -3.6291206,
         "customer": {
            "id": 9351756,
            "external_id": "9351756",
            "name": "Susan Martin",
            "email": "",
            "phone": null,
            "allow_sending_email": false,
            "allow_sending_sms": true,
            "language": null,
            "extras": null
         },
         "inventory": [
            {
               "services": [],
               "id": 42756814,
               "original_quantity": 1,
               "scan_string": "016893799",
               "name": "Package",
               "external_id": "17476748",
               "age_restricted": null,
               "price": null,
               "extras": null,
               "image": "https://site.com/images/product-placeholder.png",
               "weight": 32,
               "width": 42,
               "height": 76,
               "length": null,
               "volume": null,
               "size": null,
               "inventory": [
                  {
                     "services": [],
                     "id": 42756815,
                     "original_quantity": 1,
                     "scan_string": "8213672",
                     "name": "Fridge",
                     "external_id": "82136703",
                     "age_restricted": null,
                     "price": 2.52,
                     "extras": null,
                     "image": "https://site.com/images/product-placeholder.png",
                     "weight": 32,
                     "width": 42,
                     "height": 76
                  }
               ]
            }
         ],
         "notes": [
            {
               "id": 18673468,
               "external_id": "18673468",
               "note": "Note 3"
            },
            {
               "id": 18673467,
               "external_id": "18673467",
               "note": "Note 2"
            },
            {
               "id": 18673466,
               "external_id": "18673466",
               "note": "Note 1"
            }
         ]
      }
   ],
   "team": {
      "name": "Central Store",
      "external_id": "ABC123"
   },
   "customer": {
      "id": 9351754,
      "external_id": "9351754",
      "name": "Susan Martin",
      "email": "",
      "phone": null
   },
   "service_plan": {
      "service_plan_id": 63,
      "service_plan_name": "DIY",
      "service_plan_external_id": "DIY"
   },
   "preparation_status_id": 0,
   "preparation_status": "ACKNOWLEDGED",
   "request_id": "b42493e2-d7f0-41e6-87aa-38294d336917",
   "quote_id": null,
   "packages": [
    {
      "id": 1,
      "external_id": "testing_1",
      "fleet_external_id": "fleet_id",
      "label_url": "/label/url.zpl",
      "name": "optional package name",
      "description": "optional package description",
      "notes": "optional package notes",
      "sequence_number": null,
      "merchant_id": 123,
      "weight_value": 400,
      "weight_unit": "g",
      "volume_value": 5,
      "volume_unit": "l",
      "width_value": 100,
      "width_unit": "mm",
      "height_value": 54,
      "height_unit": "mm",
      "length_value": 45,
      "length_unit": "mm",
      "extras": { "a": 1 },
      "created_at": "2021-12-23 17:38:44.734000",
      "updated_at": "2021-12-23 17:38:44.734000",
      "delete_at": null
    },
    {
      "id": 2,
      "external_id": "testing_2",
      "fleet_external_id": "fleet_id_2",
      "label_url": "/label/url2.zpl",
      "name": "optional package name",
      "description": "optional package description",
      "notes": "optional package notes",
      "sequence_number": null,
      "merchant_id": 123,
      "weight_value": 12892,
      "weight_unit": "g",
      "volume_value": 420,
      "volume_unit": "l",
      "width_value": 32,
      "width_unit": "mm",
      "height_value": 46,
      "height_unit": "mm",
      "length_value": 10,
      "length_unit": "mm",
      "extras": { "a": 2 },
      "created_at": "2021-12-23 17:38:44.734000",
      "updated_at": "2021-12-23 17:38:44.734000",
      "delete_at": null
    }
  ]
}

📘

Customer Object

There are 3 Customer objects in this webhook:

  1. Waypoint 1 : This is the Store / Warehouse / Pickup location.
  2. Waypoint 2 : This is the End Customer, the one who is receiving the order/delivery.
  3. Customer on the root level : This is the Customer who placed the order. Usually, this is the same as the customer on the 2nd waypoint.

If you are looking to store the "Customer's" details, you most likely want to store the information from the customer object on the 2nd waypoint.

BODY PARAMS

id

Int32

Bringg's unique ID for this order

external_id

string

The merchant client's Order ID

title

string

Title of the order

priority

Int32

Sequence number of the order in a route

type

string

Type of task. The options are

  • pickup - this order needs to be picked up
  • delivery - this order needs to be delivered
  • pickup_and_delivery Both a pickup and a dropoff need to take place at the same destination/stop (Very seldom used)

extras

Array of JSONs

Custom param-value pairs. This is very specific to a particular merchant. It is not commonly used.

way_points

Array of JSONs

An array of 2 JSONs containing the following waypoint information:

  • id
  • position
  • pickup_dropoff_option
  • scheduled_at
  • asap
  • customer
  • name
  • address
  • address_second_line
  • done
  • address_type
  • location_name
  • no_earlier_than
  • no_later_than
  • lat
  • lng
  • phone
  • note
  • zipcode
  • borough
  • city
  • state
  • customer

    JSON

    A JSON containing the following fields from the Customer object associated with this order:

  • id
  • name
  • phone
  • email
  • external_id
  • 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".

    inventory

    Array of JSONs

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

    notes

    Array of JSONs

    An array of JSONs containing notes added to this order. Each note contains an id, external_id and text of the note (string). Most likely, you only need to save down the text of the note.
    Please note: There is no limit to the character length of the note, nor is there a limit to how many notes could be in the array.
    However, it is unlikely that there will be more than one or 2 notes in the array.

    team

    JSON

    A JSON which contains the following fields from the Team object associated with this order (a Team is usually a Store or Warehouse or Restaurant):

  • name
  • external_id
  • request_id

    Int32

    Bringg's reference ID for logging purposes. This can be safely ignored!