> For the complete documentation index, see [llms.txt](https://apidoc.247express.vn/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apidoc.247express.vn/english-1.0.6/customer/create-an-order.md).

# Create an order

## Recipient Address

For addresses with a **3-level structure** (Province/City, District, Ward/Commune — based on Vietnam’s administrative divisions **before July 1, 2025**), provide the following fields:

* **ReceiverProvinceName**: Recipient’s province/city name.
* **ReceiverDistrictName**: Recipient’s district name.
* **ReceiverWardName**: Recipient’s ward/commune name.

For addresses with a **2-level structure** (Province/City, Ward/Commune — based on Vietnam’s administrative divisions **from July 1, 2025**), provide the following fields:

* **ReceiverProvinceName**: Recipient’s province/city name.
* <mark style="color:red;">**ReceiverDistrictName**</mark><mark style="color:red;">: Leave null.</mark>
* **ReceiverWardName**: Recipient’s ward/commune name.

## CustomerApiCreateOrder

<mark style="color:green;">`POST:`</mark>`/Api/Customer/CustomerAPICreateOrder`

**Headers**

| Name     | Value          |
| -------- | -------------- |
| ClientID | From login api |
| Token    | From login api |

**Body**

<table><thead><tr><th width="235">Name</th><th width="131">Type</th><th>Description</th></tr></thead><tbody><tr><td>ClientHubID<mark style="color:red;">*</mark></td><td>integer</td><td>ClientHubID (Required when not passed CusWareHouseID)</td></tr><tr><td>CusWareHouseID</td><td>string</td><td>ShopID/WareHouseID (Required when not passed ClientHubID)</td></tr><tr><td>ContactName</td><td>string</td><td>Contact name</td></tr><tr><td>ContactPhone</td><td>string</td><td>Contact phone</td></tr><tr><td>SenderAddress</td><td>string</td><td>Sender full address</td></tr><tr><td>DirectSenderName</td><td>string</td><td>Direct sender name</td></tr><tr><td>ReceiverPhone</td><td>string</td><td>Recipient's phone.</td></tr><tr><td>ReceiverName</td><td>string</td><td>Recipient's name.</td></tr><tr><td>ReceiverAddress<mark style="color:red;">*</mark></td><td>string</td><td>Recipient's full address (2-level format: house number, Street name, Ward name, Province name / 3-level format: house number, Street name, Ward name, District name, Province name).</td></tr><tr><td>ReceiverProvinceName<mark style="color:red;">*</mark></td><td>string</td><td>Recipient's Province name. (2-level format and 3-level format)</td></tr><tr><td>ReceiverDistrictName<mark style="color:red;">*</mark></td><td>string</td><td>Recipient's District name. This field must be omitted or set to <code>null</code> when using the <strong>new 2-level address format</strong> (Commune/Ward + Province/City), following Vietnam’s administrative changes effective from July 1st, 2025.</td></tr><tr><td>ReceiverWardName</td><td>string</td><td>Recipient's Ward name.</td></tr><tr><td>ReceiveCompanyName</td><td>string</td><td>recipient company name</td></tr><tr><td>RealWeight</td><td>number</td><td>Real weight(kg).</td></tr><tr><td>Length</td><td>number</td><td>Length (cm).</td></tr><tr><td>Width</td><td>number</td><td>Width (cm).</td></tr><tr><td>Height</td><td>number</td><td>Height (cm).</td></tr><tr><td>Quantity</td><td>integer</td><td>Quantity package.</td></tr><tr><td>Note</td><td>string</td><td>Note.</td></tr><tr><td>ServiceTypeID</td><td>string</td><td>Service code.</td></tr><tr><td>MailerType</td><td>string</td><td>Code type of freight: HH - Goods. TL - Document.</td></tr><tr><td>CODAmount</td><td>number</td><td>The amount of COD will be collected from the recipient.</td></tr><tr><td>ExternalCode</td><td>string</td><td>Customer order code (max length: 20).</td></tr><tr><td>ReferenceCode</td><td>string</td><td>Customer reference code</td></tr><tr><td>SpecialInstructionId</td><td>number</td><td>Special note code for COD orders only: 1 - Show the goods. 2 - Do not show the goods.</td></tr><tr><td>InformFee</td><td>number</td><td>Declared value. Cases to note when declaring: 1 - Price calculation volume >= 2.5kg need to choose type = HH (goods). 2 - Type = HH (goods), required to enter the declared value (InformFee). 3 - If you choose DVBH (insurance service), you must enter the declared value(InformFee)</td></tr><tr><td>ExtraServices</td><td>array</td><td>List of VAT Services</td></tr><tr><td>Packages</td><td>array</td><td><pre class="language-json" data-overflow="wrap"><code class="lang-json">{
    "PackageID": "", //PackageID,
    "Length": 100, // Length (cm) (Required when entering in Height, Width),
    "Width": 50, // Width (cm)(Required when entering in Height, Length),
    "Height": 80, // Height (cm) (Required when entering in Width, Length),
    "RealWeight": 25 //Real weight (kg)
}
</code></pre><p>(*)The number of Packages must be equal to Quantity property. In case Quantity = 1 thenPackages = []</p></td></tr><tr><td>COPAmt</td><td>number</td><td>COP amount (Cash on pickup)</td></tr><tr><td>RequestedDeliveryTime</td><td>datetime</td><td>Requested delivery time (only applicable to delivery service units that support scheduled delivery)</td></tr><tr><td>RequestedDeliveryType</td><td>string</td><td>Delivery appointment type:
<br>"DUNGGIO": On-time
<br>"TRUOCGIO": Before the specified time
<br>(only applicable to delivery service units that support scheduled delivery)</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
    "Errors": [],
    "ErrorCode": "0",
    "OrderInfo": {
        "OrderCode": "HD000003",
        "ReferenceCode": "HD000003",
        "ExternalCode": "HD000003",
        "TotalServiceCost": 44176,
        "ExtraServices": [
            {
                "ServiceName": "Chuyển phát nhanh",
                "ServiceID": "DE",
                "Cost": 16800
            },
            {
                "ServiceName": "Hàng đông lạnh",
                "ServiceID": "HDL",
                "Cost": 15000
            },
            {
                "ServiceName": "Báo phát",
                "ServiceID": "BP",
                "Cost": 5000
            },
            {
                "ServiceName": "Phí xăng dầu",
                "ServiceID": "Fuel",
                "Cost": 3360
            },
            {
                "ServiceName": "Phí VAT",
                "ServiceID": "VAT",
                "Cost": 4016
            }
        ],
        "DeliveryType": "1"
    },
    "ErrorMessage": ""
}
```

{% endtab %}

{% tab title="401" %}

```json
{
    "IsError": true,
    "ErrorMessage": "Bạn cần đăng nhập để truy cập chức năng này."
}
```

{% endtab %}
{% endtabs %}

| Name             | Type         | Description                                             |
| ---------------- | ------------ | ------------------------------------------------------- |
| Errors           | array object | Array of Errors                                         |
| ErrorCode        | string       | Error code                                              |
| ErrorMessage     | string       | Error message                                           |
| **OrderInfo**    | object       | Order Info                                              |
| OrderCode        | string       | Order ID                                                |
| ReferenceCode    | string       | Customer reference code                                 |
| ExternalCode     | string       | Customer order code                                     |
| TotalServiceCost | number       | Total Service Cost                                      |
| **ExtraService** | array object | Value-added services list                               |
| ServiceName      | string       | Value-added service name                                |
| ServiceID        | string       | Value-added service id                                  |
| Cost             | number       | Value-added service cost                                |
| DeliveryTimeType | string       | <p>Delivery by:<br>"1" - 247 Exprest<br>"2" - Other</p> |

### Example

```json
{
   "OrderInfo":{
      "ClientHubID":11583,
      "CusWareHouseID":"30984",
      "ContactName": "Trần Văn B",
      "ContactPhone": "0332318317",      
      "ReceiverPhone":"0345555777",
      "ReceiverName":"Trương Chí Nhân",
      "ReceiverAddress":"326 Võ Văn Kiệt, phường Cầu Ông Lãnh, Hồ Chí Minh, Việt Nam",
      "ReceiverProvinceName":"Hồ Chí Minh",
      "ReceiverDistrictName": null,
      "ReceiverWardName":"Phường Cầu Ông Lãnh",   
      "RealWeight":1,
      "Length":0,
      "Width":0,
      "Height":0,
      "Quantity":1,
      "Note":"Tài liệu",
      "ServiceTypeID":"DE",
      "MailerType":"TL",
      "CODAmount":0,
      "ExternalCode":"HD000003",
      "ReferenceCode": "HD000003",
      "SpecialInstructionId":1,
      "ExtraServices":[
         {
            "ServiceID":"PTN",
            "Type":2
         },
         {
            "ServiceID":"BP",
            "Type":2
         }
      ]
   }
}
```

### Error Code

{% hint style="danger" %}

* 1: Ward error&#x20;
* 2: District error&#x20;
* 3: Province error&#x20;
* 4: Duplicate ordercode&#x20;
* 5: Server error&#x20;
* 6: Was an exception&#x20;
* 9: SpecialInstruction is required&#x20;
* 10: ServiceType is required&#x20;
* 11: SenderAddred is invalid
* 12: Account is invalid&#x20;
* 15: OrderCode is required&#x20;
* 16: OrderCode is invalid
* 17: ReceiverAddress is invalid
* 18: MailerType is invalid
* 19: Quantity is invalid
* 20: Packages is invalid
* 21: Sender info is incomplete
* 25: COP amount is invalid
  {% endhint %}