# Calculate Fee

> Calculate the shipping fee for a route and parcel before creating the order.

## Endpoint

| Environment | URL |
| --- | --- |
| Production | `https://online-gateway.ghn.vn/shiip/public-api/v2/shipping-order/fee` |
| Staging | `https://dev-online-gateway.ghn.vn/shiip/public-api/v2/shipping-order/fee` |

**Method**: `POST`

## Headers

| Header | Required | Description |
| --- | --- | --- |
| `Content-Type` | Yes | `application/json` |
| `Token` | Yes | Shop token (issued by GHN) — [get a token](https://developer.ghn.vn/en/docs/token/get-token.md) |
| `ShopId` | Yes | Shop ID (int) — the shop the quote is priced for |

## Parameters

- **weight** (Int): Parcel weight (gram). Must be non-zero
- **to_district_id** (Int): Delivery district ID (from [Get District](https://developer.ghn.vn/en/docs/master-data/get-district.md))
- **to_ward_code** (String): Delivery ward code (from [Get Ward](https://developer.ghn.vn/en/docs/master-data/get-ward.md))
- **from_district_id** (Int): Pickup district ID. Default: your shop's registered address
- **from_ward_code** (String): Pickup ward code. Default: your shop's registered address
- **service_type_id** (Int): Service type, chosen by weight:<br>`2`: total weight **under 20 kg**<br>`5`: total weight **20 kg or more**, or multi-parcel orders
- **service_id** (Int): Specific service ID (from [Get Service](https://developer.ghn.vn/en/docs/master-data/get-service.md)). Alternative to `service_type_id`
- **length** (Int): Length (cm)
- **width** (Int): Width (cm)
- **height** (Int): Height (cm)
- **insurance_value** (Int): Declared value (VND), for compensation
- **cod_value** (Int): COD amount to collect (VND)
- **coupon** (String): Discount coupon code
- **items** (Object[]): Item list — same shape as [Create Order](https://developer.ghn.vn/en/docs/order/create.md); used for heavy goods

## Request Example

```bash
curl -X POST https://dev-online-gateway.ghn.vn/shiip/public-api/v2/shipping-order/fee \
  -H "Token: 5c1d8a9e-2f4b-11ed-..." \
  -H "ShopId: 92837" \
  -H "Content-Type: application/json" \
  -d '{
    "from_district_id": 1452,
    "from_ward_code": "21007",
    "to_district_id": 1444,
    "to_ward_code": "20308",
    "service_type_id": 2,
    "weight": 600,
    "length": 25,
    "width": 20,
    "height": 8,
    "insurance_value": 285000
  }'
```

## Response

### Success (HTTP 200)

_Captured from a real Staging-environment call._

```json
{
  "code": 200,
  "message": "Success",
  "data": {
    "total": 20900,
    "service_fee": 20900,
    "insurance_fee": 0,
    "cod_fee": 0,
    "pick_station_fee": 0,
    "coupon_value": 0,
    "r2s_fee": 0,
    "return_again": 0,
    "document_return": 0,
    "double_check": 0,
    "pick_remote_areas_fee": 0,
    "deliver_remote_areas_fee": 0,
    "cod_failed_fee": 0,
    "change_to_address_fee": 0,
    "change_return_address_fee": 0,
    "return": 0
  }
}
```

### Response Fields

All amounts are in VND.

| Field | Type | Description |
| --- | --- | --- |
| `total` | Int | Total fee |
| `service_fee` | Int | Base shipping fee |
| `insurance_fee` | Int | Insurance (declared-value) fee |
| `cod_fee` | Int | COD collection fee |
| `pick_station_fee` | Int | Pickup-at-station fee |
| `coupon_value` | Int | Coupon discount value |
| `r2s_fee` | Int | Re-delivery ("return to shop") fee |
| `return_again` | Int | Repeated-return fee |
| `document_return` | Int | Document-return fee |
| `double_check` | Int | Co-inspection fee |
| `pick_remote_areas_fee` | Int | Remote-area pickup fee |
| `deliver_remote_areas_fee` | Int | Remote-area delivery fee |
| `cod_failed_fee` | Int | Failed-delivery collection fee |
| `change_to_address_fee` | Int | Delivery-address-change fee |
| `change_return_address_fee` | Int | Return-address-change fee |
| `return` | Int | Return fee already recorded on the order |

## Error Codes

| code_message | HTTP | When |
| --- | --- | --- |
| `USER_ERR_COMMON` | 400 | Missing/zero `weight`, or invalid input |
| `CLIENT_NOT_OWNER_OF_SHOP` | 400 | Token does not own the shop |
| `SERVER_ERROR_COMMON` | 500 | Internal error |