Skip to main content

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.

POST /services/shipment/order

Headers​

Token: {API_TOKEN}
X-Client-Source: {PARTNER_CODE}
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
    "gam_solutions": [
      { "solution_id": 12365478 },
      { "solution_id": 12365479 },
      { "solution_id": 12365470 }
    ]
  }
}

Parameters​

ParametersRequiredDescription
orderyesObject - Order information to be sent to GHTK
productsyesArray - List of products. See the next table for detailed description of product fields
order.idyesString - Partner's order code in their system
Pickup Information
order.pick_nameyesString - Name of the contact person for pickup
order.pick_moneyyesInteger - CoD amount (in VND). If 0, no cash collection is required
order.pick_address_idnoString - Pickup location ID from the customer’s order management page. This field will take priority if not empty
order.pick_addressyesString - Short pickup address (e.g., House No. 5, Block 3, Alley 11, Lane 45)
order.pick_provinceyesString - Province/City of the pickup location
order.pick_districtyesString - District of the pickup location
order.pick_wardnoString - Ward/Commune of the pickup location
order.pick_streetnoString - Street name of the pickup location
order.pick_telyesString - Pickup contact phone number
order.pick_ext_telnoString - Extension number of the main pickup contact phone number
order.pick_emailnoString - Pickup contact email address
Delivery Information
order.nameyesString - Recipient's full name
order.addressyesString - Detailed delivery address (e.g., CT1 Building, Alley 58, Tran Binh Street)
order.provinceyesString - Province/City of the recipient
order.districtyesString - District of the recipient
order.wardyesString - Ward/Commune of the recipient
order.streetyes if order.hamlet=NoneString - Street name of the recipient (Required if Hamlet/Village/Cluster is not provided)
order.hamletyes if order.street=NoneString - Hamlet/Village/Cluster/... of the recipient. If not applicable, enter "Other" (Required if Street is not provided)
order.telyesString - Recipient’s phone number
order.ext_telnoString - Extension number of the main recipient's phone number
order.notenoString - Order note (e.g., Maximum chargeable weight: 1.00 kg). From Feb 24, 2020, max 120 characters allowed
order.emailnoString - Recipient’s email address
Return Address
order.use_return_addressnoInteger - 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_nameyesString - Return recipient name
order.return_addressyesString - Detailed return address (e.g., House A, Alley 100)
order.return_provinceyesString - Province/City of the return address
order.return_districtyesString - District of the return address
order.return_wardnoString - Ward/Commune of the return address
order.return_streetnoString - Street of the return address
order.return_telyesString - Return recipient phone number
order.return_emailnoString - Return recipient email address
Additional Information
order.is_freeshipnoInteger - 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_optionnoString - Weight unit of items in packages, either gram or kilogram. Default is kilogram
order.total_weightnoDouble - Total weight of the package. If omitted, calculated from products.weight
order.pick_work_shiftnoInteger - To indicate the order will be picked up at which time. “2” is in the afternoon and “1” is in the morning. Default value is set automatically by GHTK.
order.deliver_work_shiftnoInteger - To indicate the order will be delivered at which time. “2” is in the afternoon and “1” is in the morning. Default value is set automatically by GHTK.
order.label_idnoString - Pre-assigned order label from partner. Not available by default - service-specific configuration
order.pick_datenoString YYYY/MM/DD - Scheduled pickup date. Not available by default - service-specific configuration
order.deliver_datenoString YYYY/MM/DD - Scheduled delivery date. Not available by default - service-specific configuration
order.valueyesInteger (VNĐ) - Declared value, which is a base for insurance and compensation fee calculation when an incident occurs.
order.opmnoInteger (VNĐ) - 1 for CoD only (no delivery), 0 for default full delivery
order.pick_optionnoString - 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_methodnoString - 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.transportnoString - Shipping method: road (ground), fly (air). If invalid, GHTK will fall back to the default method
order.tagsnoArray - Order Tagging: An array of tags to label the order. The list of available tags is described in the following table
order.sub_tagsnoArray - Array - Sub Tags: An array of detailed tag information. This field is mandatory when tagging the order as a "Live Plants"
order.total_boxnoInteger - Total number of packages in the order.
order.gam_solutionsnoArray - List of Gam solution IDs applied to the order.

products parameters​

ParameterRequiredDescription
nameyesString - Product name
pricenoInteger - Product price
weightyesDouble - Product weight in kilograms
quantitynoInteger - Product quantity
product_codenoString - Product code taken from the API to get product information list
heightnoDouble - Height of the product (unit: cm)
widthnoDouble - Width of the product (unit: cm)
lengthnoDouble - Length of the product (unit: cm)

tags description​

TagDescriptionDetailed
2High-Value / SpecialGoods valued over 3,000,000 VND (for B2C shops) or 1,000,000 VND (for 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.
10Item PreviewThe recipient is able to view the product before accepting the delivery.
13Shop Call-BackA GHTK agent will contact the shop if problems such as wrong recipient information, unreachable customer, or customer refuses the parcel arise.
17Partial DeliveryCustomer 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.
18Partial ReturnSupport for delivering one product to the customer and returning the remaining items to the shop. Shipping fee is negotiated between shop and customer (default equals shipping fee). 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.
19Failed Delivery – Fee CollectedSupport for cases where the customer does not receive the product but a partial fee is collected for the shop. Default fee equals shipping fee, but the shop can adjust the amount. 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.
62Partial Delivery with Document RetrievalSupport for delivering products to the customer and returning accompanying documents (invoices, papers) with the remaining items to the shop.

sub_tags description​

Sub tag detailDescription
1Seeds
2Seedlings
3Bagged plants
4Plants in fragile pots
5Other 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.
  • Some fields in the response may be hidden.