Create an Order
Endpoint
POST /v1/orders
To request a new order to be picked up by the courier, you need to create a new order object. Make sure your Biteship Balance is sufficient when making this request. Try to request for invoice payment for more custom ordering.
If your environment is still in Staging, the courier will not pick up your request, though everything else will occur as if in live mode.
API Parameters
The name of the shipper.
The phone number of the shipper.
The email of the shipper.
The organization of the shipper.
The name of the person in the pickup location.
The phone number of the person in the pickup location.
The email of the person in the pickup location.
Complete address of the pickup location.
Additional information of the pickup location to ease pickup process.
Postal code of the pickup location.
Coordinates of the pickup location. If you use an instant courier, you must use coordinate.origin_coordinate .latitude double *REQUIRED / OPTIONAL
origin_coordinate .longitude double *REQUIRED / OPTIONAL
Show child parameters
Latitude of the pickup location.
Longitude of the pickup location.
Use the available_collection_method from Rates API. Value can be pickup, or drop_off. Default to pickup.
pickup your package will be picked by courier based on origin that you specify.
drop_off you must drop off the package to the nearest courier agent.
pickup your package will be picked by courier based on origin that you specify.
drop_off you must drop off the package to the nearest courier agent.
The name of the person in destination location.
The phone number of the person in destination location.
The email of the person in destination location.
Complete address of the destination location.
Additional information of the destination location to ease destination process.
Postal code of the destination location.
Coordinates of the destination location. If you use an instant courier, you must use coordinate.destination_coordinate .latitude double *REQUIRED / OPTIONAL
destination_coordinate .longitude double *REQUIRED / OPTIONAL
Show child parameters
Latitude of the destination location.
Longitude of the destination location.
State the COD Amount if you want to activate COD delivery.
The COD disbursement window. Value can be 7_days, 5_days, or 3_days.
7_days you will receiver your money 7 days after the item is delivered.
5_days you will receiver your money 5 days after the item is delivered.
3_days you will receiver your money 3 days after the item is delivered.
7_days you will receiver your money 7 days after the item is delivered.
5_days you will receiver your money 5 days after the item is delivered.
3_days you will receiver your money 3 days after the item is delivered.
Proof of delivery feature.
Notes for proof of delivery. It is required if proof of delivery feature is activated.
Shipping provider that will be used for this particular shipment. List of available courier can be found using Couriers API.
Courier type based on the courier company used. Each type can be different for each company. Value of type can be found within the Rates API and Couriers API.
Type of delivery order is now and scheduled.
now will generate waybill instantly and pickup right away.
scheduled will generate waybill instantly and pickup based on delivery date and delivery time.
now will generate waybill instantly and pickup right away.
scheduled will generate waybill instantly and pickup based on delivery date and delivery time.
The delivery date format: “YYYY-MM-DD”
The delivery time format: “HH:mm”
Additional information for the shipment.
You can insert any kind of data through this object for internal purposes.
You can insert your internal order id here. Must unique for each order id.
You can insert multiple custom tags (in string) for filtering your orders by tag later on.
The list of item you will send for deliveryitems .name string REQUIRED
items .description string Optional
items .category string Optional
items .sku string Optional
items .value number REQUIRED
items .quantity number REQUIRED
items .weight number REQUIRED
items .height number Optional
items .length number Optional
items .width number Optional
Show child parameters
Name of your package.
A description of your package. You can share the color, the details or any that help describing your item.
Categorization of your package, the value must be one of these table value. If empty, the default value will beothers
| Value | Description |
|---|---|
| fashion | Clothing, accessories, and personal adornments. |
| healthcare | Products related to health, wellness, and personal care. |
| food_and_drink | Items related to food and beverages. |
| electronic | Electronic devices and accessories. |
| beauty | Beauty products and cosmetics. |
| outdoor_gear | Equipment and apparel for outdoor activities. |
| home_accessories | Items that enhance the decor and functionality of the home. |
| hobby | Products related to leisure and hobbies. |
| collection | Items that belong to a particular collection or set. |
| sparepart | Replacement parts and accessories. |
| groceries | Food and household items typically purchased for regular consumption. |
| others | Miscellaneous items that don't fit into the other categories. |
Item SKU if you have one.
The value of the item.
The total of the item.
The weight of the item in grams.
The height of the item in centimeters. Item dimensions can affect the weight of your item which can cause a price different.
The length of the item in centimeters. Item dimensions can affect the weight of your item which can cause a price different.
The width of the item in centimeters. Item dimensions can affect the weight of your item which can cause a price different.
Type of Request
Order for Standard Couriers
JSON Body Request
{
"shipper_contact_name": "Amir",
"shipper_contact_phone": "088888888888",
"shipper_contact_email": "[email protected]",
"shipper_organization": "Biteship Org Test",
"origin_contact_name": "Amir",
"origin_contact_phone": "088888888888",
"origin_address": "Plaza Senayan, Jalan Asia Afrik...",
"origin_note": "Deket pintu masuk STC",
"origin_postal_code": 12440,
"destination_contact_name": "John Doe",
"destination_contact_phone": "088888888888",
"destination_contact_email": "[email protected]",
"destination_address": "Lebak Bulus MRT...",
"destination_postal_code": 12950,
"destination_note": "Near the gas station",
"courier_company": "jne",
"courier_type": "reg",
"courier_insurance": 500000,
"delivery_type": "now",
"order_note": "Please be careful",
"metadata": {},
"items": [
{
"name": "Black L",
"description": "White Shirt",
"category": "fashion",
"value": 165000,
"quantity": 1,
"height": 10,
"length": 10,
"weight": 200,
"width": 10
}
]
}
Order for Instant Couriers
JSON Body Request
{
"shipper_contact_name": "Amir",
"shipper_contact_phone": "088888888888",
"shipper_contact_email": "[email protected]",
"shipper_organization": "Biteship Org Test",
"origin_contact_name": "Amir",
"origin_contact_phone": "088888888888",
"origin_address": "Plaza Senayan, Jalan Asia Afrik...",
"origin_note": "Deket pintu masuk STC",
"origin_coordinate": {
"latitude": -6.2253114,
"longitude": 106.7993735
},
"destination_contact_name": "John Doe",
"destination_contact_phone": "088888888888",
"destination_contact_email": "[email protected]",
"destination_address": "Lebak Bulus MRT...",
"destination_note": "Near the gas station",
"destination_coordinate": {
"latitude": -6.28927,
"longitude": 106.77492000000007
},
"courier_company": "grab",
"courier_type": "instant",
"courier_insurance": 500000,
"delivery_type": "now",
"order_note": "Please be careful",
"metadata": {},
"items": [
{
"name": "Black L",
"description": "White Shirt",
"category": "fashion",
"category": "fashion",
"value": 165000,
"quantity": 1,
"height": 10,
"length": 10,
"weight": 200,
"width": 10
}
]
}
Order for Cash on Delivery
JSON Body Request
{
"shipper_contact_name": "Amir",
"shipper_contact_phone": "088888888888",
"shipper_contact_email": "[email protected]",
"shipper_organization": "Biteship Org Test",
"origin_contact_name": "Amir",
"origin_contact_phone": "088888888888",
"origin_address": "Plaza Senayan, Jalan Asia Afrik...",
"origin_note": "Deket pintu masuk STC",
"origin_postal_code": 12440,
"destination_contact_name": "John Doe",
"destination_contact_phone": "088888888888",
"destination_contact_email": "[email protected]",
"destination_address": "Lebak Bulus MRT...",
"destination_note": "Near the gas station",
"destination_postal_code": 12950,
"destination_cash_on_delivery": 500000,
"destination_cash_on_delivery_type": "7_days",
"courier_company": "sicepat",
"courier_type": "reg",
"courier_insurance": 500000,
"delivery_type": "now",
"order_note": "Please be careful",
"metadata": {},
"items": [
{
"name": "Black L",
"description": "White Shirt",
"category": "fashion",
"value": 165000,
"quantity": 1,
"height": 10,
"length": 10,
"weight": 200,
"width": 10
}
]
}
Order for Drop Off collection method
JSON Body Request
{
"shipper_contact_name": "Amir",
"shipper_contact_phone": "088888888888",
"shipper_contact_email": "[email protected]",
"shipper_organization": "Biteship Org Test",
"origin_contact_name": "Amir",
"origin_contact_phone": "088888888888",
"origin_address": "Plaza Senayan, Jalan Asia Afrik...",
"origin_note": "Deket pintu masuk STC",
"origin_postal_code": 12440,
"origin_collection_method": "drop_off",
"destination_contact_name": "John Doe",
"destination_contact_phone": "088888888888",
"destination_contact_email": "[email protected]",
"destination_address": "Lebak Bulus MRT...",
"destination_note": "Near the gas station",
"destination_postal_code": 12950,
"courier_company": "sicepat",
"courier_type": "reg",
"courier_insurance": 500000,
"delivery_type": "now",
"order_note": "Please be careful",
"metadata": {},
"items": [
{
"name": "Black L",
"description": "White Shirt",
"category": "fashion",
"value": 165000,
"quantity": 1,
"height": 10,
"length": 10,
"weight": 200,
"width": 10
}
]
}
*When you send origin and destination value, you must at least choose one type of origin or destination. Origin and destination must at least have postal codes, coordinates or area ids. You do not need to insert all of the three values.
API Response
Order Created
Response
{
"success": true,
"message": "Order successfully created",
"object": "order",
"id": "5dd599ebdefcd4158eb8470b",
"draft_order_id": null,
"shipper": {
"name": "Biteship Indonesia",
"email": "[email protected]",
"phone": "08123456789",
"organization": "Biteship"
},
"origin": {
"contact_name": "Akbar",
"contact_phone": "08123456789",
"coordinate": {
"latitude": -6.2253114,
"longitude": 106.7993735
},
"address": "Plaza Senayan, Jalan Asia Afrika, RT.1/RW.3",
"note": "Deket pintu masuk STC",
"postal_code": 12440
},
"destination": {
"contact_name": "Bambang",
"contact_phone": "088888888888",
"contact_email": "[email protected]",
"address": "Lebak Bulus MRT, Jalan R.A.Kartini",
"note": "Di deket pintu MRT",
"proof_of_delivery": {
"use": false,
"fee": 0,
"note": null,
"link": null
},
"cash_on_delivery": {
"id": "77bb0f60b029822ecb1411da",
"amount": 500000,
"amount_currency": "IDR",
"fee": 20000,
"fee_currency": "IDR",
"note": null,
"type": "7_days"
},
"coordinate": {
"latitude": -6.28927,
"longitude": 106.77492000000007
},
"postal_code": 12950
},
"courier": {
"tracking_id": "6de509ebdefgh4158ij3451c",
"waybill_id": null,
"company": "anteraja",
"name": null, // Deprecated
"phone": null, // Deprecated
"driver_name": null,
"driver_phone": null,
"driver_photo_url": null,
"driver_plate_number": null,
"type": "reg",
"link": null,
"insurance": {
"amount": 500000,
"amount_currency": "IDR",
"fee": 2500,
"fee_currency": "IDR",
"note": ""
},
"routing_code": null
},
"delivery": {
"datetime": "2029-09-24T12:00+07:00",
"note": null,
"type": "now",
"distance": 9.8,
"distance_unit": "kilometer"
},
"reference_id": null,
"items": [
{
"name": "Black L",
"description": "Feast/Bangkok'19 Invasion",
"sku": null,
"value": 165000,
"quantity": 1,
"length": 10,
"width": 10,
"height": 10,
"weight": 200
}
],
"extra": [],
"currency": "IDR",
"tax_lines": [],
"price": 48000,
"metadata": {},
"note": "Please be careful",
"status": "confirmed"
}
Failed to Create Order due to Reference ID already used
Response
{
"success": false,
"error": "Reference id has already been used before. Please input other reference id",
"code": 40002060,
"details": {
"order_id": "660105377589b8dea565208b", // The order that uses given reference id
"waybill_id": "1028309128390", // The waybill of order that uses given reference id
"reference_id": "66010548c90b557a9e2dd7a4" // Given reference id
}
}