Create delivery

Delivery Lifecycle

Deliveries pass the following lifecycle (with status codes):
pending (10) - this is the initial state of a delivery once it is created in the system

confirmed (20) - A delivery status will be changed to confirmed once a courier is in route to pick it up

waiting (30) - A delivery is waiting once the courier has arrived to the pickup location and is now waiting to pick the package

picked_up (40) - A delivery is picked_up once the courier has collected the item.

driving (50) - A delivery is driving once the courier is en-route to deliver the package.

at_drop_off (60) - Once the courier has arrived to the delivery destination.

Finite status states:
rejected (80) - The delivery was not accepted due to 3 (three) reasons:

  1. Invalid phone number.
    "description":"drop_off_contact: drop off contact validation failed - missing phone number"

  2. Drop off address is out of polygon (Distribution area).
    "description":"drop_off: Drop off not allowed because it is out of the defined service area for the selected pickup point"

  3. Manual Rejecting due to specific requirements.
    description":"free text","error":"manual reject"}

  4. Failed to GeoCode
    "description":"Problem with Address - Failed to geocode"

completed (70) - The delivery was completed (delivered) successfully

not_delivered (90) - The delivery arrived at the drop off address but was not completed (delivered)

cancelled (100) - The delivery was cancelled

Request

Resource

POST v1/delivery/deliveries

With this endpoint you create deliveries.

There are several ways to create deliveries in Gett's system:

  1. Create a Bundle and add one by one delivery, or several deliveries into the bundle
  2. Create bulk of deliveries (without creating a Bundle) that will be picked up from the same time and place. In the case, our system will create the bundle
  3. Create one by one delivery (with adding scheduled_at ) and our system will aggregate the deliveries into a bundle. For enabling this option, please contact our account manager.
  4. Create a single delivery (point-to-point). if you choose that option, creating a bundle is not necessarily. in order to create such an option add "avoid_aggregation": true into the delivery object section.

Authorization

OAuth 2.0 bearer token with Delivery scope.

Query Parameters

Name

Type

Description

business_id

string

Unique identifier representing a Business.

get_exact_deliveries (optional)

boolean

If get_exact_deliveries = true:
The Response will include only the new created deliveries, and not the whole Bundle attached to these deliveries

Body Parameters

Name

Type

Description

bundle_id(optional)

string

If provided - we will add the deliveries provided to the existing bundle.

If not provided - a new bundle will be created with the deliveries and provided bundle params.

product_id(optional)

string

If bundle_id is not provided - product_id is mandatory

scheduled_at(optional)

timetamp

if bundle_id is not provided, this will be used when creating the bundle.
format

display_identifier(optional)

string

if bundle_id is not provided, this will be used as display identifier for bundle.

avoid_aggregation (optional)

boolean

When the boolean value is true, the order will be created as Point to Point order, without aggregation.

Default value = false

pickup_interval_from (optional)

timetamp

A time range for pickup time.
If scheduled_at wont be provide, the pickup time will be set from pickup_interval_from value
format

pickup_interval_until (optional)

timetamp

A time range for pickup time.
format

deliveries

Delivery

An array of delivery requests

pickup_contact

object

This object contains the pickup contact name and the pickup phone number

pickup_contact.name

string

The name of the pickup person.

pickup_contact.phone_number

string

The phone number of the pickup person.

pickup

object

Pickup address details.

pickup.lat

float

The latitude of the pickup.

pickup.lng

float

The longitude of the pickup.

pickup.address

string

The address of the pickup

pickup.note (optional)

string

A note for the pickup address, (eg. "3rd floor") - Up to 500 characters

return_drop_off (optional)

object

Return details

return_drop_off.lat (optional)

float

The latitude of the return.

return_drop_off.lng (optional)

float

The longitude of the return.

return_drop_off. address (optional)

string

The address of the return

return_drop_off.note (optional)

string

A note for the return address, (eg. "3rd floor") - Up to 500 characters

drop_off_contact (optional)

object

Return contact details

Return details.name (optional)

string

The name of the return person

Return details.phone_number (optional)

string

The phone number of the return person

deliveries[x].external_identifier (optional)

string

Any identifier to help you map deliveries created with your entities

deliveries[x].drop_off

object

Drop off address details.

deliveries[x].drop_off.lat (optional)

float

The latitude of the destination.

deliveries[x].drop_off.lng (optional)

float

The longitude of the destination.

deliveries[x].drop_off.address

string

The address of the destination.

deliveries[x].drop_off.note (optional)

string

A note for the destination address, (eg. "3rd floor") - Up to 500 characters

deliveries[x].return_contact

object

The contact person in the drop off

deliveries[x].drop_off_contact.name

string

The name of the drop off contact

deliveries[x].drop_off_contact.phone_number

string

The phone number of the drop off contact

deliveries[x].display_identifier (optional)

string

An identifier which will be displayed for the supplier performing the delivery while picking the delivery up (for ex. stringified barcode)

deliveries[x].deliver_from (optional)

timetamp

The beginning time of the expected delivery time window.
format

deliveries[x].deliver_until (optional)

timetamp

The end time of the expected delivery time window.
format

deliveries[x].client_price (optional)

float

The total end customer price (Needed for enabling post payment)

deliveries[x].delivery_price (optional)

float

The delivery price (for post payment price breakdown)

deliveries[x].vendor (optional)

object

Vendor data

deliveries[x].vendor.name

string

The vendor's name

deliveries[x].parcels

array of objects

If you don't provide parcels, we implicitly create 1 parcel with same identifier as delivery

deliveries[x].parcels[y].size_alias (optional)

string

Parcel size alias is configured for each integration to map between generic sizes (e.g. XS, S, M, L) to dimensions in cm

deliveries[x].parcels[y].length (optional)

int

Parcel length in cm.

deliveries[x].parcels[y].width (optional)

int

Parcel width in cm.

deliveries[x].parcels[y].height (optional)

int

Parcel height in cm.

deliveries[x].parcels[y].weight (optional)

float

Parcel weight in kg.

deliveries[x].parcels[y].display_identifier (optional)

string

Parcel label (code or id). Will be presented to the courier for easier identification of the parcel. Will override deliveries[x].display_identifier

deliveries[x].parcels[y].barcode (Deprecated - Use barcodes instead)

string

deliveries[x].parcels[y].barcodes (optional)

Array of strings

Array of parcel barcodes as printed on the labels.
Currently we support only homogeneous bundles, eg. either all parcels have a barcode or none does.
This barcode will be scanned by the courier when picking up the parcel.

deliveries[x].parcels[y].external_identifier (optional)

string

Any identifier to help you map parcels created with your entities .

deliveries[x].parcels[y].items (optional)

objects

A list of items for each parcel

deliveries[x].parcels[y].items[z].external_id

string

Item external ID

deliveries[x].parcels[y].items[z].name

string

Item name

deliveries[x].parcels[y].items[z].quantity

int

Item quantity

deliveries[x].parcels[y].items[z].price

float

Item price

deliveries[x].parcels[y].items[z].vat_rate

float

Item vat rate percentage

deliveries[x].parcels[y].items[z].exemplars

objects

Item instances

deliveries[x].parcels[y].items[z].exemplars[h].external_id

string

Exemplar external ID

deliveries[x].parcels[y].items[z].exemplars[h].barcode

string

Exemplar barcode

deliveries[x].age_verification_required (optional)

boolean

This parameter forces the courier to add ID-based age verification including the number, date of birth, and issue year of the recipient’s ID.

Default value is: false

deliveries[x].external_payment_confirmation(optional)

boolean

This parameter inform our system that a payment status must be set by company.
for more info click here Payment status

Default value : false

Request

curl -X POST -H 'Authorization: Bearer [TOKEN]' \
             -H 'Content-Type: application/json' \
             -d '{
  "product_id": "04a5a00a-553a-4a2a-bc68-f3bde4828e3a",
  "scheduled_at": "2020-08-26T16:54:29Z",
  "display_identifier": "Test ",
  "avoid_aggregation": true,

    "pickup": {
        "lat": 32.109528,
        "lng": 34.840088,
        "address": "HaBarzel 25, Tel Aviv",
        "note": "Apt: 3, floor: 4"
    },
    "pickup_contact": {
        "name": "John Doe",
        "phone_number": "972528801054"
    },
    "return_drop_off": {
        "lat": 32.1133727,
        "lng": 34.836637,
        "address": "Habarzel 12, Tel Aviv ",
        "note": "Flor 3, next to elivatot"
    },
    "return_contact": {
        "name": "Mark",
        "phone_number": "972528801054"
    },
    "deliveries": [
        {
            "drop_off": {
                "lat": 32.111626,
                "lng": 34.840796,
                "address": "HaArad 7, Tel Aviv",
                "note": "Floor 5, Door 7"
            },
            "drop_off_contact": {
                "name": "Dan",
                "phone_number": "972598666690"
            },
            "external_identifier": "O-76547654",
            "display_identifier": "J48793U897879",
            "deliver_from": "2018-11-29T18:00:00+02:00",
            "deliver_until": "2018-11-29T20:00:00+02:00",
            "client_price": 45.4,
            "delivery_price": 35.4,
            "vendor": {
                "name": "gillette"
            },
            "parcels": [
                {
                    "display_identifier": "3214",
                    "external_identifier": "Test",
                    "size_alias": "M",
                    "length": 125,
                    "width": 23,
                    "height": 10,
                    "weight": 3.15,
                    "barcodes": [
                        "0123452",
                        "hgcgf5656"
                    ],
                    "items": [
                        {
                            "external_id": "6041404739000",
                            "name": "Oxford",
                            "quantity": 2,
                            "price": 293.15,
                            "vat_rate": 10,
                            "exemplars": [
                                {
                                    "external_id": 
                                    "6390000414047",
                                    "barcode":"01ygitftyf23452"
                                },
                                {
                                    "external_id": 
                                    "4140463900007",
                                    "barcode": "6527394735"
                                }
                            ]
                        }
                    ]
                }
            ]
        },
        {
            "drop_off": {
                "lat": 32.116846,
                "lng": 34.838704,
                "address": "Dvorah Haneviah 74, Tel Aviv"
            },
            "drop_off_contact": {
                "name": "Dean Smith",
                "phone_number": "972593877655"
            },
            "parcels": [
                {
                    "barcodes": [
                        "1234test"
                    ]
                },
                {
                    "barcodes": [
                        "1X24C54324"
                    ]
                }
            ],
            "external_payment_confirmation":true,
            "display_identifier": "M87483H8F889"
        }
    ]
}
' \
'https://api.gett.com/v1/delivery/deliveries?business_id=[BUSINESS_ID]'

Response

{
  "company_id": "IL-7348",
  "bundle_id": "B-86f49daf10e940daa1adc5b2ce19757e",
  "created_at": "2020-09-07T13:44:18.340125Z",
  "scheduled_at": "2020-09-12T16:54:29Z",
  "return_mode": "never",
  "deliveries": [
    {
      "id": "DR-1f3dc243b3b4455781dab0f42b1358b7",
      "bundle_id": "B-86f49daf10e940daa1adc5b2ce19757e",
      "product_id": "86c31386-f596-48ff-9458-c70634414c9b",
      "display_identifier": "J48793U897879",
      "status": "rejected",
      "status_code": 80,
      "cannot_deliver_info": null,
      "courier": null,
      "pickup": {
        "address": "HaBarzel 25, Tel Aviv",
        "lat": 32.109528,
        "lng": 34.840088,
        "note": "Apt: 3, floor: 4"
      },
      "drop_off": {
        "address": "HaArad 7, Tel Aviv",
        "lat": 32.111626,
        "lng": 34.840796,
        "note": "Floor 5, Door 7"
      },
      "pickup_contact": {
        "name": "Itai Sagi",
        "phone_number": "972554754407"
      },
      "drop_off_contact": {
        "name": "Dan",
        "phone_number": "972598666690"
      },
      "verifications": null,
      "started_at": null,
      "scheduled_at": "2020-09-12T16:54:29Z",
      "arrived_at": null,
      "picked_up_at": null,
      "ended_at": null,
      "deliver_from": "2018-11-29T16:00:00Z",
      "deliver_until": "2018-11-29T18:00:00Z",
      "parcels": [
        {
          "display_identifier": "3214",
          "external_identifier": "Test",
          "barcode": "0123452",
          "barcodes": [
            "0123452",
            "hgcgf5656"
          ],
          "size_alias": "B",
          "length": 125,
          "width": 23,
          "height": 10,
          "weight": 3.15,
          "items": [
            {
              "external_id": "6041404739000",
              "name": "Steve Madden Mens Tabloid Oxford",
              "quantity": 2,
              "price": 293.15,
              "vat_rate": 10,
              "exemplars": [
                {
                  "external_id": "6390000414047",
                  "barcode": "01ygitftyf23452",
                  "status": "initial",
                  "cannot_deliver_info": null
                },
                {
                  "external_id": "4140463900007",
                  "barcode": "6527394735",
                  "status": "initial",
                  "cannot_deliver_info": null
                }
              ],
              "status": "initial",
              "cannot_deliver_info": null
            }
          ],
          "status": "initial",
          "cannot_deliver_info": null
        }
      ],
      "client_price": 45.4,
      "delivery_price": 35.4,
      "vendor": {
        "name": "gillette"
      },
      "route_identifier": null,
      "external_identifier": "O-76547654",
      "created_at": "2020-09-07T13:44:18.43344Z",
      "rejection_info": {
        "description": "client_price: post-payment is not enabled for the company"
      },
      "age_verification_required": false,
      "external_payment_confirmation":false,
      "order_id_representation": "WI7002131612BS",
      "order_from": "DeliveryApi-d5f0c8a2adb0d9f8df6e4c8735bfdf9f62ac07c99719554bba5430cdd706ab6d"
    },
    {
      "id": "DR-ee322c11937444dabb113e245711776c",
      "bundle_id": "B-86f49daf10e940daa1adc5b2ce19757e",
      "product_id": "86c31386-f596-48ff-9458-c70634414c9b",
      "display_identifier": "M87483H8F889",
      "status": "pending",
      "status_code": 10,
      "cannot_deliver_info": null,
      "courier": null,
      "pickup": {
        "address": "HaBarzel 25, Tel Aviv",
        "lat": 32.109528,
        "lng": 34.840088,
        "note": "Apt: 3, floor: 4"
      },
      "drop_off": {
        "address": "Dvorah Haneviah 74, Tel Aviv",
        "lat": 32.116846,
        "lng": 34.838704,
        "note": ""
      },
      "pickup_contact": {
        "name": "Itai Sagi",
        "phone_number": "972554754407"
      },
      "drop_off_contact": {
        "name": "Dean Smith",
        "phone_number": "972593877655"
      },
      "verifications": null,
      "started_at": null,
      "scheduled_at": "2020-09-12T16:54:29Z",
      "arrived_at": null,
      "picked_up_at": null,
      "ended_at": null,
      "deliver_from": null,
      "deliver_until": null,
      "parcels": [
        {
          "display_identifier": "M87483H8F889_1",
          "barcode": "2X24C54324",
          "barcodes": [
            "2X24C54324"
          ],
          "size_alias": "",
          "length": 0,
          "width": 0,
          "height": 0,
          "weight": 0,
          "items": [
            {
              "external_id": "",
              "name": "M87483H8F889_1",
              "quantity": 1,
              "price": 0,
              "vat_rate": 0,
              "exemplars": null,
              "status": "initial",
              "cannot_deliver_info": null
            }
          ],
          "status": "initial",
          "cannot_deliver_info": null
        },
        {
          "display_identifier": "M87483H8F889_2",
          "barcode": "1X24C54324",
          "barcodes": [
            "1X24C54324"
          ],
          "size_alias": "",
          "length": 0,
          "width": 0,
          "height": 0,
          "weight": 0,
          "items": [
            {
              "external_id": "",
              "name": "M87483H8F889_2",
              "quantity": 1,
              "price": 0,
              "vat_rate": 0,
              "exemplars": null,
              "status": "initial",
              "cannot_deliver_info": null
            }
          ],
          "status": "initial",
          "cannot_deliver_info": null
        }
      ],
      "client_price": null,
      "delivery_price": null,
      "vendor": {
        "name": ""
      },
      "route_identifier": null,
      "external_identifier": null,
      "created_at": "2020-09-07T13:44:18.442521Z",
      "age_verification_required": false,
      "external_payment_confirmation":true,
      "order_id_representation": "IP5234348570XH",
      "order_from": "DeliveryApi-d5f0c8a2adb0d9f8df6e4c8735bfdf9f62ac07c99719554bba5430cdd706ab6d"
    }
  ],
  "display_identifier": "Test ",
  "process_type": "only_optimize",
  "external_identifier": "bundle external identifier"

}

Sandbox

Resource:

POST v1/delivery_sandbox/deliveries?business_id={{company_id}}

More info can be found here


Did this page help you?