3. Order Creation API

Partners send a list of orders to Giaohangtietkiem’s system via APIs. Once the orders are successfully saved into GHTK’s system, the system will return a corresponding list of orders containing the relevant details of each one.

Hyperlink

POST /services/shipment/order

Headers

Token: {API_TOKEN}
X-Client-Source: {PARTNER_CODE}

HTTP

POST /services/shipment/order/?ver=1.5 HTTP/1.1
Token: APITokenSample-ca441e70288cB0515F310742
X-Client-Source: S308157
Content-Type: application/json
{
  "products": [{
  "name": "bút",
  "weight": 0.1,
  "quantity": 1,
  "product_code": 1241
}, {
  "name": "tẩy",
  "weight": 0.2,
  "quantity": 1,
  "product_code": 1254
}],
  "order": {
  "id": "a4",
  "pick_name": "HCM-nội thành",
  "pick_address": "590 CMT8 P.11",
  "pick_province": "TP. Hồ Chí Minh",
  "pick_district": "Quận 3",
  "pick_ward": "Phường 1",
  "pick_tel": "0911222333",
  "tel": "0911222333",
  "name": "GHTK - HCM - Noi Thanh",
  "address": "123 nguyễn chí thanh",
  "province": "TP. Hồ Chí Minh",
  "district": "Quận 1",
  "ward": "Phường Bến Nghé",
  "hamlet": "Khác",
  "is_freeship": "1",
  "pick_date": "2016-09-30",
  "pick_money": 47000,
  "note": "Khối lượng tính cước tối đa: 1.00 kg",
  "value": 3000000,
  "transport": "fly",
  "pick_option":"cod" ,// Đơn hàng xfast yêu cầu bắt buộc pick_option là COD
  "deliver_option" : "xteam", // nếu lựa chọn kiểu vận chuyển xfast
}
}

CURL

curl -X POST -H "Token: APITokenSample-ca441e70288cB0515F310742" \
-H "X-Client-Source: S308157" \
-H "Content-Type: application/json" \
-d '{"products":[{"name":"bút","weight":0.1,"quantity":1,"product_code": 1241},{"name":"tẩy","weight":0.2,"quantity":1,"product_code": 1254}],"order":{"id":"a4","pick_name":"HCM-nội thành","pick_address":"590 CMT8 P.11","pick_province":"TP. Hồ Chí Minh","pick_district":"Quận 3","pick_ward":"Phường 1","pick_tel":"0911222333","tel":"0911222333","name":"GHTK - HCM - Noi Thanh","address":"123 nguyễn chí thanh","province":"TP. Hồ Chí Minh","district":"Quận 1","ward":"Phường Bến Nghé","hamlet":"Khác","is_freeship":"1","pick_date":"2016-09-30","pick_money":47000,"note":"Khối lượng tính cước tối đa: 1.00 kg","value":3000000,"transport":"fly","pick_option":"cod","deliver_option" : "xteam","pick_session" : 2}}' "https://services.giaohangtietkiem.vn/services/shipment/order"

PHP

<?php
$order = '{"products":[{"name":"bút","weight":0.1,"quantity":1,"product_code":"23304A3MHLMVMXX625"},{"name":"tẩy","weight":0.2,"quantity":1,"product_code":""}],"order":{"id":"a4","pick_name":"HCM-nội thành","pick_address":"590 CMT8 P.11","pick_province":"TP. Hồ Chí Minh","pick_district":"Quận 3","pick_ward":"Phường 1","pick_tel":"0911222333","tel":"0911222333","name":"GHTK - HCM - Noi Thanh","address":"123 nguyễn chí thanh","province":"TP. Hồ Chí Minh","district":"Quận 1","ward":"Phường Bến Nghé","hamlet":"Khác","is_freeship":"1","pick_date":"2016-09-30","pick_money":47000,"note":"Khối lượng tính cước tối đa: 1.00 kg","value":3000000,"transport":"fly","pick_option":"cod","deliver_option":"xteam","pick_session":2,"tags":[1]}}';

$curl = curl_init();

curl_setopt_array($curl, array(
   CURLOPT_URL => "https://services.giaohangtietkiem.vn/services/shipment/order",
   CURLOPT_RETURNTRANSFER => true,
   CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
   CURLOPT_CUSTOMREQUEST => "POST",
   CURLOPT_POSTFIELDS => $order,
   CURLOPT_HTTPHEADER => array(
       "Content-Type: application/json",
       "Token: APITokenSample-ca441e70288cB0515F310742",
       "Content-Length: " . strlen($order),
   ),
));

$response = curl_exec($curl);
curl_close($curl);

echo 'Response: ' . $response;
?>

Parameters

Parameters	Required	Description
order	yes	Object - Order information to be sent to GHTK
products	yes	Array - List of products. See the next table for detailed description of product fields
order.id	yes	String - Partner's order code in their system
Pickup Information
order.pick_name	yes	String - Name of the contact person for pickup
order.pick_money	yes	Integer - CoD amount (in VND). If 0, no cash collection is required
order.pick_address_id	no	String - Pickup location ID from the customer’s order management page. This field will take priority if not empty
order.pick_address	yes	String - Short pickup address (e.g., House No. 5, Block 3, Alley 11, Lane 45)
order.pick_province	yes	String - Province/City of the pickup location
order.pick_district	yes	String - District of the pickup location
order.pick_ward	no	String - Ward/Commune of the pickup location
order.pick_street	no	String - Street name of the pickup location
order.pick_tel	yes	String - Pickup contact phone number
order.pick_email	no	String - Pickup contact email address
Delivery Information
order.name	yes	String - Recipient's full name
order.address	yes	String - Detailed delivery address (e.g., CT1 Building, Alley 58, Tran Binh Street)
order.province	yes	String - Province/City of the recipient
order.district	yes	String - District of the recipient
order.ward	yes	String - Ward/Commune of the recipient (Required if street is not provided)
order.street	yes	String - Street name of the recipient (Required if ward/commune is not provided)
order.hamlet	yes	String - Hamlet/Village/Cluster/... of the recipient. If not applicable, enter "Other"
order.tel	yes	String - Recipient’s phone number
order.note	no	String - Order note (e.g., Maximum chargeable weight: 1.00 kg). From Feb 24, 2020, max 120 characters allowed
order.email	yes	String - Recipient’s email address
Return Address
order.use_return_address	no	Integer - Default is 0. This field accepts either a value of 0 or 1. A value of 0 means the return address is the same as the pickup address, so the return address fields can be omitted. A value of 1 means a different return address is used, and all corresponding return address fields must be provided
order.return_name	yes	String - Return recipient name
order.return_address	yes	String - Detailed return address (e.g., House A, Alley 100)
order.return_province	yes	String - Province/City of the return address
order.return_district	yes	String - District of the return address
order.return_ward	no	String - Ward/Commune of the return address
order.return_street	no	String - Street of the return address
order.return_tel	yes	String - Return recipient phone number
order.return_email	yes	String - Return recipient email address
Additional Information
order.is_freeship	no	Integer - Free shipping for receiver. 1 means receiver pays only CoD amount that equals (pick_money), 0 means receiver pays CoD + shipping fee. Default is 0
order.weight_option	no	String - Weight unit of items in packages, either gram or kilogram. Default is kilogram
order.total_weight	no	Double - Total weight of the package. If omitted, calculated from products.weight
order.pick_work_shift	no	Integer - Pickup work shift: 1 = morning, 2 = afternoon, 3 = evening. GHTK will auto-assign by default
order.deliver_work_shift	no	Integer - Delivery work shift: 1 = morning, 2 = afternoon, 3 = evening. GHTK will auto-assign by default
order.label_id	no	String - Pre-assigned order label from partner. Not available by default - service-specific configuration
order.pick_date	no	String YYYY/MM/DD - Scheduled pickup date. Not available by default - service-specific configuration
order.deliver_date	no	String YYYY/MM/DD - Scheduled delivery date. Not available by default - service-specific configuration
order.expired	no	String YYYY/MM/DD hh:mm:ss - Auto-calculated time. Not available by default - service-specific configuration
order.value	yes	Integer (VNĐ) - Declared value, which is a base for insurance and compensation fee calculation when an incident occurs.
order.opm	no	Integer (VNĐ) - 1 for CoD only (no delivery), 0 for default full delivery
order.pick_option	no	String - Either cod or post. Default is cod. Indicates whether the item is picked up (cod) or dropped off by shop at post office (post)
order.actual_transfer_method	no	String - This field saves the transfer method of an order, default is by air (fly). If on ground (road), GHTK will notify about the change
order.transport	no	String - Shipping method: road (ground), fly (air). If invalid, GHTK will fall back to the default method
order.deliver_option	no	String - Value is xteam if using xfast delivery option
order.tags	no	Array - Order Tagging: An array of tags to label the order. The list of available tags is described in the following table
order.sub_tags	no	Array - Array - Sub Tags: An array of detailed tag information. This field is mandatory when tagging the order as a "Live Plants"

products parameters

Parameter	Required	Description
name	yes	String - Product name
price	no	Integer - Product price
weight	yes	Double - Product weight in kilograms
quantity	no	Integer - Product quantity
product_code	no	String - Product code taken from the API to get product information list

tags description

Tag	Description	Detailed
1	Fragile	Items made from materials that can easily break or be damaged in transit. A 20 % surcharge is added to the total service fee (shipping + insurance, if any). If damage occurs, GHTK takes full responsibility for the order tagged Fragile.
2	High‑Value / Special	Goods valued over 3,000,000 VND (of B2C shops) or 1,000,000 VND (of C2C shops). High-value goods will incur an additional insurance fee, which covers risks during transportation or storage. An additional insurance fee of 0.5 % of the product price is applied. In cases that the product is missing, GHTK will reimburse 100 % of the declared value (up to 20,000,000 VND) if valid proof of value/origin is provided (e.g., purchase invoices, valid receipts that match the product information on GHTK’s system, etc.). In cases where the seller cannot provide proof of origin and value of the goods, compensation will be limited to a maximum of 4 times the shipping fee.
7	Dry Agricultural Produce / Food	Dry food that needs no special storage is added a 10% surcharge of the total service fee (shipping + insurance, if any) . For items with short shelf life (< 30 days), the promised delivery date must be ≤ 7 days from pickup; otherwise the order will not be automatically stored in the warehouse; GHTK will return the package to the shop.
10	Item Preview	The recipient is able to view the product before accepting the delivery.
11	Partial Inspection	The recipient may count items or check conditions without breaking factory seals. Surcharge: 2,000 VND per order.
13	Shop Call‑Back	A GHTK agent will contact the shop if problems such as wrong recipient information, unreachable customer, customer refuses the parcel arise.
17	Partial Delivery	Customer pays only for the items kept; remaining items are returned to the shop. Return fee: 5,000 VND for in‑province shipping, 50 % of initial shipping fee for inter‑province shipping.
18	Partial Return	Customers may refuse items but still have to pay a fee to the shop. Default fee equals shipping fee, editable by shop. Returned portion is treated as a return order. Return fee: 5,000 VND for in‑province shipping, 50 % of initial shipping fee for inter‑province shipping
19	Failed Delivery – Fee Collected	Customers may refuse items but still have to pay a fee to the shop. Default fee equals shipping fee, editable by shop. Returned portion is treated as a return order. Return fee: 5,000 VND for in‑province shipping, 50 % of initial shipping fee for inter‑province shipping. Note: Partners must include the not_delivered_fee field with a value greater than 0 and less than or equal to 20,000,000 VND
20	Original Packaging	Manufacturer‑boxed goods must remain intact during transit.Surcharge: 1,000 VND per order.
22	Letters / Documents	Letters and documents are packed securely to prevent damage.
39	Fresh / Frozen Food	If fresh and frozen items with shelf life in 1 day are undeliverable, GHTK returns them to the shop the same day.
40	Small Items	Items have weight ≤ 300 g and combined dimensions ≤ 20 cm. These items must be packed in an envelope of at least 110 × 120 mm.
41	Non‑Stackable Items	Items easily crushed or deformed; must not have other parcels stacked on top.
42	Orientation‑Sensitive Items	Items that must remain upright or in a specific orientation to stay safe and intact
75	Live Plants	Orders tagged “Live Plants” are transported via a dedicated handling flow to extend storage time and minimize external appearance damage.

---

sub_tags description

Sub tag detail	Description
1	Seeds
2	Seedlings
3	Bagged plants
4	Plants in fragile pots
5	Other types of plants

Response

When an order is successfully created:

{
  "success": true,
  "message": "",
  "order": {
    "partner_id": "123123a",
    "label": "S1.A1.2001297581",
    "area": "1",
    "fee": "30400",
    "insurance_fee": "15000",
    "tracking_id": 2001297581,
    "estimated_pick_time": "Sáng 2017-07-01",
    "estimated_deliver_time": "Chiều 2017-07-01",
    "products": [],
    "status_id": 2
  }
}

When an error occurs:

{
  "success": false,
  "message": "Chưa có thông tin order"
}

warning

GHTK's process does not allow an order code to be pushed again if it has already been successfully created on the GHTK’s system. In the case where the order.id already exists on the GHTK system occurs, the API will return an error along with the following information:

• partner_id: the partner's order code
• ghtk_label: GHTK's order label
• created: the time when the order was created
• status: the current status of the order

{
  "success": false,
  "message": "Mã đơn hàng của bạn đã tồn tại trên hệ thống GHTK",
  "error": {
      "code" : "ORDER_ID_EXIST",
      "partner_id" : "a4", // id trong request đẩy sang của bạn
      "ghtk_label": "S1.A1.1737345", // nhãn đơn GHTK, tương ứng với id của bạn
      "created": "2016-11-02T12:18:39+07:00",
      "status": 5  // trạng thái đơn hàng hiện tại trên hệ thống GHTK, tra bảng mã trạng thái đơn trong phần webhook
  }
}

Note

info

Note: The unit of weight GHTK uses for each product is kilograms (KG)

warning

Note: The initial shipping fee will be calculated based on the total weight of all products in the order.

warning

Note:

• If the order is set is_freeship = 1,the COD will only collect from the recipient an amount equal to pick_money
• If the value is set to 0, the COD will collect from the recipient an amount equal to pick_money + shipping fee of the order. The default value is 0.