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

NameTypeDescription
business_idstringUnique identifier representing a Business.
get_exact_deliveries (optional)booleanIf get_exact_deliveries = true:
The Response will include only the new created deliveries, and not the whole Bundle attached to these deliveries

Body Parameters

NameTypeDescription
bundle_id(optional)stringIf 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)stringIf bundle_id is not provided - product_id is mandatory
scheduled_at(optional)timetampif bundle_id is not provided, this will be used when creating the bundle.
format
display_identifier(optional)stringif bundle_id is not provided, this will be used as display identifier for bundle.
avoid_aggregation (optional)booleanWhen the boolean value is true, the order will be created as Point to Point order, without aggregation.

Default value = false
pickup_interval_from (optional)timetampA 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)timetampA time range for pickup time.
format
deliveriesDeliveryAn array of delivery requests
pickup_contactobjectThis object contains the pickup contact name and the pickup phone number
pickup_contact.namestringThe name of the pickup person.
pickup_contact.phone_numberstringThe phone number of the pickup person.
pickupobjectPickup address details.
pickup.latfloatThe latitude of the pickup.
pickup.lngfloatThe longitude of the pickup.
pickup.addressstringThe address of the pickup
pickup.note (optional)stringA note for the pickup address, (eg. "3rd floor") - Up to 500 characters
return_drop_off (optional)objectReturn details
return_drop_off.lat (optional)floatThe latitude of the return.
return_drop_off.lng (optional)floatThe longitude of the return.
return_drop_off. address (optional)stringThe address of the return
return_drop_off.note (optional)stringA note for the return address, (eg. "3rd floor") - Up to 500 characters
drop_off_contact (optional)objectReturn contact details
Return details.name (optional)stringThe name of the return person
Return details.phone_number (optional)stringThe phone number of the return person
deliveries[x].external_identifier (optional)stringAny identifier to help you map deliveries created with your entities
deliveries[x].drop_offobjectDrop off address details.
deliveries[x].drop_off.lat (optional)floatThe latitude of the destination.
deliveries[x].drop_off.lng (optional)floatThe longitude of the destination.
deliveries[x].drop_off.addressstringThe address of the destination.
deliveries[x].drop_off.note (optional)stringA note for the destination address, (eg. "3rd floor") - Up to 500 characters
deliveries[x].return_contactobjectThe contact person in the drop off
deliveries[x].drop_off_contact.namestringThe name of the drop off contact
deliveries[x].drop_off_contact.phone_numberstringThe phone number of the drop off contact
deliveries[x].display_identifier (optional)stringAn 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)timetampThe beginning time of the expected delivery time window.
format
deliveries[x].deliver_until (optional)timetampThe end time of the expected delivery time window.
format
deliveries[x].client_price (optional)floatThe total end customer price (Needed for enabling post payment)
deliveries[x].delivery_price (optional)floatThe delivery price (for post payment price breakdown)
deliveries[x].vendor (optional)objectVendor data
deliveries[x].vendor.namestringThe vendor's name
deliveries[x].parcelsarray of objectsIf you don't provide parcels, we implicitly create 1 parcel with same identifier as delivery
deliveries[x].parcels[y].size_alias (optional)stringParcel 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)intParcel length in cm.
deliveries[x].parcels[y].width (optional)intParcel width in cm.
deliveries[x].parcels[y].height (optional)intParcel height in cm.
deliveries[x].parcels[y].weight (optional)floatParcel weight in kg.
deliveries[x].parcels[y].display_identifier (optional)stringParcel 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 stringsArray 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)stringAny identifier to help you map parcels created with your entities .
deliveries[x].parcels[y].items (optional)objectsA list of items for each parcel
deliveries[x].parcels[y].items[z].external_idstringItem external ID
deliveries[x].parcels[y].items[z].namestringItem name
deliveries[x].parcels[y].items[z].quantityintItem quantity
deliveries[x].parcels[y].items[z].pricefloatItem price
deliveries[x].parcels[y].items[z].vat_ratefloatItem vat rate percentage
deliveries[x].parcels[y].items[z].exemplarsobjectsItem instances
deliveries[x].parcels[y].items[z].exemplars[h].external_idstringExemplar external ID
deliveries[x].parcels[y].items[z].exemplars[h].barcodestringExemplar barcode
deliveries[x].age_verification_required (optional)booleanThis 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)booleanThis 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?