v1

latestOpenAPI 3.0.12026-08-061158187.8 KB

Order API

Create order

Creates a new delivery order.

To avoid creating duplicate orders, we recommend sending a requested_tracking_number so that the API can use it to generate the waybill tracking number.

For marketplace platforms, marketplace information is required. Using the provided seller_id, the API automatically creates a new Ninja Van shipper account for your marketplace seller, if the seller_id wasn't previously registered in Ninja Van's systems.

For corporate accounts, corporate information is required. The corporate branch account has to be created under the corporate HQ before an order creation request can be made. Using branch_id field, the API creates orders for the corporate branch identified by the given branch ID.

post/{countryCode}/4.1/orders

Path parameters

countryCode'SG' | 'MY' | 'TH' | 'ID' | 'VN' | 'PH' | 'MM' required

Country code.

Headers

Authorizationstring required

Your Bearer token.

Request body

Indicates the type of service. Used to inform Ninja Van on what jobs to schedule for this order.

service_level'Standard' | 'Express' | 'Sameday' | 'Nextday' required

Shipment service level.

requested_tracking_numberstring

If your shipper account is a prefixless account, then requested_tracking_number is required.

If your shipper account has a tracking number prefix configured, then the API concatenates your prefix with the requested_tracking_number to generate the waybill tracking number.

If requested_tracking_number isn't provided, then the API automatically generates a random tracking number and concatenates your prefix with it to generate the waybill tracking number.

A generic prefix is used for this request, if your account does not have a prefix and if the requested_tracking_number is not provided.

The total length of the generated tracking_number is further validated based on your shipper settings.

The default length for tracking_number is around 18 characters. If the requested_tracking_number is too short, the API auto-pads the value with zeros (0).

Check with us if you have any questions regarding your shipper account settings.

Example request

{
  "service_type": "Parcel",
  "service_level": "Standard",
  "requested_tracking_number": "1234-56789",
  "reference": {
    "merchant_order_number": "SHIP-1234-56789"
  },
  "from": {
    "name": "John Doe",
    "phone_number": "+60138201527",
    "email": "john.doe@gmail.com",
    "address": {
      "address1": "17 Lorong Jambu 3",
      "address2": "",
      "area": "Taman Sri Delima",
      "city": "Simpang Ampat",
      "state": "Pulau Pinang",
      "address_type": "office",
      "country": "MY",
      "postcode": "51200"
    }
  },
  "to": {
    "name": "Jane Doe",
    "phone_number": "+60103067174",
    "email": "jane.doe@gmail.com",
    "address": {
      "address1": "Jalan PJU 8/8",
      "address2": "",
      "area": "Damansara Perdana",
      "city": "Petaling Jaya",
      "state": "Selangor",
      "address_type": "home",
      "country": "MY",
      "postcode": "47820"
    }
  },
  "parcel_job": {
    "is_pickup_required": true,
    "pickup_address_id": "98989012",
    "pickup_service_type": "Scheduled",
    "pickup_service_level": "Standard",
    "pickup_date": "2021-12-15",
    "pickup_timeslot": {
      "start_time": "09:00",
      "end_time": "12:00",
      "timezone": "Asia/Kuala_Lumpur"
    },
    "pickup_instructions": "Pickup with care!",
    "delivery_instructions": "If recipient is not around, leave parcel in power riser.",
    "delivery_start_date": "2021-12-16",
    "delivery_timeslot": {
      "start_time": "09:00",
      "end_time": "12:00",
      "timezone": "Asia/Kuala_Lumpur"
    },
    "dimensions": {
      "weight": 1.5
    },
    "items": [
      {
        "item_description": "Sample description",
        "quantity": 1,
        "is_dangerous_good": false
      }
    ]
  }
}

Response

Order successfully created.

requested_tracking_numberstring

The requested tracking number of the order.

tracking_numberstring required

Indicates the type of service. Used to inform Ninja Van on what jobs to schedule for this order.

service_level'Standard' | 'Express' | 'Sameday' | 'Nextday'

Shipment service level.

Example response

{
  "requested_tracking_number": "1234-56789",
  "tracking_number": "PREFIX1234-56789",
  "service_type": "Parcel",
  "service_level": "Standard",
  "reference": {
    "merchant_order_number": "SHIP-1234-56789"
  },
  "from": {
    "name": "John Doe",
    "phone_number": "+60138201527",
    "email": "john.doe@gmail.com",
    "address": {
      "address1": "17 Lorong Jambu 3",
      "address2": "",
      "area": "Taman Sri Delima",
      "city": "Simpang Ampat",
      "state": "Pulau Pinang",
      "address_type": "office",
      "country": "MY",
      "postcode": "51200"
    }
  },
  "to": {
    "name": "Jane Doe",
    "phone_number": "+60103067174",
    "email": "jane.doe@gmail.com",
    "address": {
      "address1": "Jalan PJU 8/8",
      "address2": "",
      "area": "Damansara Perdana",
      "city": "Petaling Jaya",
      "state": "Selangor",
      "address_type": "home",
      "country": "MY",
      "postcode": "47820"
    }
  },
  "parcel_job": {
    "is_pickup_required": true,
    "pickup_service_type": "Scheduled",
    "pickup_service_level": "Standard",
    "pickup_address_id": "98989012",
    "pickup_date": "2021-12-15",
    "pickup_timeslot": {
      "start_time": "09:00",
      "end_time": "12:00",
      "timezone": "Asia/Kuala_Lumpur"
    },
    "pickup_approximate_volume": "Less than 3 Parcels",
    "pickup_instructions": "Pickup with care!",
    "delivery_start_date": "2021-12-16",
    "delivery_timeslot": {
      "start_time": "09:00",
      "end_time": "12:00",
      "timezone": "Asia/Kuala_Lumpur"
    },
    "delivery_instructions": "If recipient is not around, leave parcel in power riser.",
    "allow-weekend_delivery": true,
    "dimensions": {
      "weight": 1.5
    },
    "items": [
      {
        "item_description": "Sample description",
        "quantity": 1,
        "is_dangerous_good": false
      }
    ]
  }
}