> For new integrations, EasyParcel recommends the NextGen API: https://developer.easyparcel.com/

# Rate Checking

> EasyParcel API · Malaysia · MarketPlace · version 1.4.0.0
> Page: https://developers.easyparcel.com/my/marketplace/rate-checking · Markdown: https://developers.easyparcel.com/my/marketplace/rate-checking.md · PDF: https://developers.easyparcel.com/pdf/Malaysia_MarketPlace_1.4.0.0.pdf

This enable rate checking from all courier companies in EasyParcel platform. User need to provide sender and receiver address to check the shipment rate.

## Endpoint

- Method: `POST`
- Demo URL: `https://demo.connect.easyparcel.my/?ac=MPRateCheckingBulk`
- Live URL: `https://connect.easyparcel.my/?ac=MPRateCheckingBulk`
- Body: `application/x-www-form-urlencoded`. Nested fields use PHP `http_build_query` names, e.g. `bulk[0][pick_code]`.
- Action: `MPRateCheckingBulk`

## Request parameters

### Request L1

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `authentication` | string(25) | Yes | Obtain from EasyParcel IT administrator |
| `api` | string(25) | Yes | Obtain from registered account. |
| `bulk` | array | Yes | (Refer to [Request L2](#request-l2)) |
| `exclude_fields` | array | Optional | Exclude certain fields from response. Supported values: “rates.\*.dropoff_point”, “rates.\*.pickup_point” |
| `byoc_no_timeout` | boolean | Optional | By default the live BYOC rate lookup is bounded to 5 seconds so it can never delay the normal rates; if it does not respond within 5 seconds, BYOC rates are simply omitted. Set to true to wait for the full BYOC courier response (no 5-second limit) |
| `api_rate_on` | boolean | Optional | Some courier services, such as UPS and FedEx, may experience slower response times. To maintain overall performance, the default timeout is set to 3 seconds. Set this parameter to true to extend the timeout to 60 seconds, allowing more time for slower courier responses. Set this parameter to false if you do not require quotations from these couriers, which helps maintain overall API performance. |
| `auto_apply_coupon` | boolean | Optional | Controls whether eligible coupons are automatically applied during quotation. When enabled, the quoted shipment prices will be displayed after the applicable coupon discount is applied. If this parameter is not specified, the behavior will follow the auto-apply coupon settings configured in EasyParcel. |

### Request L2 · `bulk[]` {#request-l2}

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `pick_code` | string(10) | Yes | Sender's postcode. |
| `pick_state` | string(35) | Yes | Sender's state. (Refer to [Appendix III](https://developers.easyparcel.com/my/marketplace/appendix/state-code-list.md)) |
| `pick_country` | string(2) | Yes | Sender's country (“MY”). |
| `send_code` | string(10) | Yes | Receiver's postcode. |
| `send_state` | string(35) | Yes | Receiver's state. (Refer to [Appendix III](https://developers.easyparcel.com/my/marketplace/appendix/state-code-list.md)) |
| `send_country` | string(2) | Yes | Receiver's country (“MY”). |
| `weight` | double(8,2) | Yes | The weight of the parcel. |
| `width` | double(8,2) | Optional | The width of the parcel. |
| `length` | double(8,2) | Optional | The length of the parcel. |
| `height` | double(8,2) | Optional | The height of the parcel. |
| `date_coll` | date | Optional | Check the available pickup date. If the date is left empty, the default will be today’s date. Format : “YYYY-MM-DD” |
| `parcel_value` | double(8,2) | Optional | The value of parcel in RM |
| `addon_tracking_whatsapp_enabled	` | boolean | Optional | By enabling this feature, your price quotes will automatically include the WhatsApp tracking service fee |
| `addon_tracking_sms_enabled` | boolean | Optional | By enabling this feature, your price quotes will automatically include the tracking SMS service fee |
| `addon_tracking_email_enabled` | boolean | Optional | By enabling this feature, your price quotes will automatically include the tracking email service fee |

## Sample code

### PHP

```php
<?php
$domain = "https://demo.connect.easyparcel.my/?ac=";

$action = "MPRateCheckingBulk";
$postparam = array(
    'authentication' => 'xxxxxx',
    'api' => 'xxxxxx',
    'bulk' => array(
        array(
            'pick_code' => '10050',
            'pick_state' => 'png',
            'pick_country' => 'MY',
            'send_code' => '11950',
            'send_state' => 'png',
            'send_country' => 'MY',
            'weight' => '5',
            'width' => '0',
            'length' => '0',
            'height' => '0',
            'date_coll' => '2017-11-10',
        ),
        array(
            'pick_code' => '14300',
            'pick_state' => 'png',
            'pick_country' => 'MY',
            'send_code' => '81100',
            'send_state' => 'jhr',
            'send_country' => 'MY',
            'weight' => '10',
            'width' => '0',
            'length' => '0',
            'height' => '0',
            'date_coll' => '2017-11-10',
        ),
    ),
    'exclude_fields' => array(
        'rates.*.pickup_point',
    ),
);

$url = $domain.$action;
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($postparam));
curl_setopt($ch, CURLOPT_HEADER, 0);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);

ob_start();
$return = curl_exec($ch);
ob_end_clean();
curl_close($ch);

$json = json_decode($return);
echo "<pre>"; print_r($json); echo "</pre>";
?>
```

### cURL

```bash
curl -X POST 'https://demo.connect.easyparcel.my/?ac=MPRateCheckingBulk' \
  --data-urlencode 'authentication=xxxxxx' \
  --data-urlencode 'api=xxxxxx' \
  --data-urlencode 'bulk[0][pick_code]=10050' \
  --data-urlencode 'bulk[0][pick_state]=png' \
  --data-urlencode 'bulk[0][pick_country]=MY' \
  --data-urlencode 'bulk[0][send_code]=11950' \
  --data-urlencode 'bulk[0][send_state]=png' \
  --data-urlencode 'bulk[0][send_country]=MY' \
  --data-urlencode 'bulk[0][weight]=5' \
  --data-urlencode 'bulk[0][width]=0' \
  --data-urlencode 'bulk[0][length]=0' \
  --data-urlencode 'bulk[0][height]=0' \
  --data-urlencode 'bulk[0][date_coll]=2017-11-10' \
  --data-urlencode 'bulk[1][pick_code]=14300' \
  --data-urlencode 'bulk[1][pick_state]=png' \
  --data-urlencode 'bulk[1][pick_country]=MY' \
  --data-urlencode 'bulk[1][send_code]=81100' \
  --data-urlencode 'bulk[1][send_state]=jhr' \
  --data-urlencode 'bulk[1][send_country]=MY' \
  --data-urlencode 'bulk[1][weight]=10' \
  --data-urlencode 'bulk[1][width]=0' \
  --data-urlencode 'bulk[1][length]=0' \
  --data-urlencode 'bulk[1][height]=0' \
  --data-urlencode 'bulk[1][date_coll]=2017-11-10' \
  --data-urlencode 'exclude_fields[0]=rates.*.pickup_point'
```

## Response

### Response L1

| Field | Type | Description | Remarks |
| --- | --- | --- | --- |
| `api_status` | string(10) | Validation result | (Refer to [Appendix I](https://developers.easyparcel.com/my/marketplace/appendix/api-return-status.md)) |
| `error_code` | int(5) | Error code | (Refer to [Appendix I](https://developers.easyparcel.com/my/marketplace/appendix/api-return-status.md)) |
| `error_remark` | string(100) | Error message | (Refer to [Appendix I](https://developers.easyparcel.com/my/marketplace/appendix/api-return-status.md)) |
| `result` | array | Result for rate checking | (Refer to [Response L2](#response-l2)) |

### Response L2 · `result` {#response-l2}

| Field | Type | Description | Remarks |
| --- | --- | --- | --- |
| `status` | string(10) | The status of the rate checking. | Fail / Success |
| `remarks` | string(100) | The error message for rate checking. |  |
| `rates` | array | The response of the rate checking | (Refer to [Response L3](#response-l3)) |

### Response L3 · `rates` {#response-l3}

| Field | Type | Description | Remarks |
| --- | --- | --- | --- |
| `rate_id` | string (15) | Rate ID |  |
| `service_detail` | string (15) | Service Detail | dropoff, pickup, dropoff/pickup |
| `service_id` | string (15) | Service ID |  |
| `service_type` | string (10) | Type of service | parcel/ document |
| `courier_id` | string (10) | Courier ID |  |
| `courier_logo` | string (300) | Courier logo |  |
| `scheduled_start_date` | string (50) | Scheduled pickup for parcel. |  |
| `pickup_date` | date | The date to pickup the parcel. | Same day pickup only available before 12pm. |
| `delivery` | string (100) | The day(s) to deliver the parcel. |  |
| `price` | double(8,2) | Total price | shipping + addon |
| `addon_price` | double(8,2) | Addon service pricing |  |
| `shipment_price` | double(8,2) | Shipping price |  |
| `require_min_order` | int(11) | Courier require minimum parcel |  |
| `service_name` | string (100) | Service name |  |
| `courier_name` | string (100) | Courier name |  |
| `dropoff_point` | array | Drop-off point for it’s courier service | (Refer to [Response L4](#response-l4)) |
| `pickup_point` | array | Pickup point for it’s courier service | (Refer to [Response L4](#response-l4)) |
| `import_tax_charges` | double(8,2) | DDP Tax Charges (For International Shipment) |  |
| `import_duty_charges` | double(8,2) | DDP Duty Charges (For International Shipment) |  |
| `handling_charges` | double(8,2) | DDP Handling Charges (For International Shipment) |  |
| `byoc_charges` | double(8,2) | EasyParcel's BYOC platform charge for this shipment | BYOC rates only |
| `byoc_charges_tax` | double(8,2) | Tax on the BYOC platform charge | BYOC rates only |
| `seller_payable_amount` | double(8,2) | The amount that is actually payable to EasyParcel. For a normal courier this equals the price. For a BYOC courier it is the BYOC platform charge plus its tax (byoc_charges + byoc_charges_tax + add-on price if enabled) |  |
| `ddp_available` | boolean | Whether this service support DDP |  |
| `ddp_only` | boolean | Whether this service only support DDP, not support DDU |  |
| `handling_charges_tax` | double(8,2) | DDP Handling Charges Tax |  |
| `coupon_discount` | double(8,2) | Amount of discount if coupon auto apply is on |  |
| `coupon_codes` | array | List of coupon codes used if coupon auto apply is on |  |
| `coupons` | array | List of coupon used with the details if coupon auto apply is on |  |
| `price_before_coupon` | double(8,2) | Total price before apply coupon |  |
| `auto_apply_coupon` | boolean | Whether auto apply coupon during quotation is on |  |
| `auto_apply_coupon_payment` | boolean | Whether auto apply coupon during payment is on |  |

### Response L4 · `dropoff_point` / `pickup_point` {#response-l4}

| Field | Type | Description | Remarks |
| --- | --- | --- | --- |
| `point_id` | string(25) | Drop-off point ID |  |
| `point_name` | string(100) | Drop-off point name |  |
| `point_contact` | string(10) | Drop-off point contact |  |
| `point_addr1` | string(10) | Drop-off point address line 1 |  |
| `point_addr2` | string(10) | Drop-off point address line 2 |  |
| `point_addr3` | string(10) | Drop-off point address line 3 |  |
| `point_addr4` | string(10) | Drop-off point address line 4 |  |
| `point_postcode` | string(10) | Drop-off point postcode |  |
| `point_city` | string(10) | Drop-off point city |  |
| `point_state` | string(10) | Drop-off point state | (Refer to [Appendix III](https://developers.easyparcel.com/my/marketplace/appendix/state-code-list.md)) |
| `price` | double(8,2) | Drop-off point fee |  |

## Response samples

### Success

```json
{
  "api_status": "Success",
  "error_code": "0",
  "error_remark": "",
  "result": [
    {
      "REQ_ID": "",
      "status": "Success",
      "remarks": "",
      "rates": [
        {
          "rate_id": "EP-RR0M2NL",
          "service_detail": "dropoff/pickup",
          "service_id": "EP-CS0CH",
          "service_type": "parcel",
          "courier_id": "EP-CR0A",
          "courier_logo": "https://s3-ap-southeast-1.amazonaws.com/easyparcel-static/Public/source/general/img/couriers/Pos_Laju.jpg",
          "scheduled_start_date": "2020-07-21 Tuesday",
          "pickup_date": "2020-07-21",
          "delivery": "3-5 working day(s)",
          "price": "8.00",
          "addon_price": "0.00",
          "shipment_price": "8.00",
          "require_min_order": 0,
          "service_name": "Poslaju Same Day Pick up (within WM)",
          "courier_name": "POSLAJU NATIONAL COURIER",
          "dropoff_point": [{
              "point_id": "EP-CB0MI",
              "point_name": "Pos Malaysia Banting",
              "point_contact": "03-3187 1437",
              "point_addr1": "No. 101 Jalan Bunga, Pekan 2",
              "point_addr2": "42700",
              "point_addr3": "",
              "point_addr4": "",
              "point_postcode": "Banting",
              "point_city": "",
              "point_state": "sgr",
              "start_time": "00:00:00",
              "end_time": "00:00:00",
              "price": 0
            }],
          "pickup_point": []
        },
        {
          "rate_id": "EP-RR0MCOV",
          "service_detail": "pickup",
          "service_id": "EP-CS0KS",
          "service_type": "parcel",
          "courier_id": "EP-CR0Z",
          "courier_logo": "https://s3-ap-southeast-1.amazonaws.com/easyparcel-static/Public/source/general/img/couriers/CJ_Century.jpg",
          "scheduled_start_date": "2020-07-21 Tuesday",
          "pickup_date": "2020-07-21",
          "delivery": "3-5 working day(s)",
          "price": "7.80",
          "addon_price": "0.00",
          "shipment_price": "7.80",
          "require_min_order": 0,
          "service_name": "CJ Century",
          "courier_name": "CJ Century Logistics Sdn Bhd",
          "dropoff_point": [],
          "pickup_point": []
        },
        {
          "rate_id": "EP-RR0914N",
          "service_detail": "dropoff",
          "service_id": "EP-CS09J",
          "service_type": "parcel",
          "courier_id": "EP-CR0C",
          "courier_logo": "https://s3-ap-southeast-1.amazonaws.com/easyparcel-static/Public/source/general/img/couriers/DHLeC.jpg",
          "scheduled_start_date": "2020-07-21 Tuesday",
          "pickup_date": "2020-07-21",
          "delivery": "3-5 working day(s)",
          "price": "7.30",
          "addon_price": "0.00",
          "shipment_price": "7.30",
          "require_min_order": 0,
          "service_name": "DHL eCommerce (Dropoff only)",
          "courier_name": "DHL eCommerce",
          "dropoff_point": [{
              "point_id": "EP-CB02X",
              "point_name": "DHL ServicePoint - E3 Farmasi",
              "point_contact": "",
              "point_addr1": "71",
              "point_addr2": "Jalan Bunga Tanjung 6A",
              "point_addr3": "Taman Muda",
              "point_addr4": "",
              "point_postcode": "68000",
              "point_city": "Ampang",
              "point_state": "sgr",
              "start_time": "00:00:00",
              "end_time": "00:00:00",
              "price": 0
            }],
          "pickup_point": []
        }
      ]
    }
  ]
}
```

### Fail

```json
{
  "api_status":"Error",
  "error_code":"1",
  "error_remark":"Required authentication key",
  "result":[
    
  ]
}
```

## Referenced appendices

Copied from the appendix pages linked above.

### Appendix III: State Code List

Source: https://developers.easyparcel.com/my/marketplace/appendix/state-code-list.md

| Short State Name | Full State Name |
| --- | --- |
| jhr | Johor |
| kdh | Kedah |
| ktn | Kelantan |
| mlk | Melaka |
| nsn | Negeri Sembilan |
| phg | Pahang |
| prk | Perak |
| pls | Perlis |
| png | Pulau Pinang |
| sgr | Selangor |
| trg | Terengganu |
| kul | Kuala Lumpur |
| pjy | Putra Jaya |
| srw | Sarawak |
| sbh | Sabah |
| lbn | Labuan |

### Appendix I: API Return Status

Source: https://developers.easyparcel.com/my/marketplace/appendix/api-return-status.md

| api_status | error_code | error_remark | Explanation |
| --- | --- | --- | --- |
| Success | 0 |  |  |
| Error | 1 | Required authentication key | Missing authentication param |
| Error | 2 | Invalid authentication key |  |
| Error | 3 | Required api key | Missing API key param |
| Error | 4 | Invalid api key |  |
| Error | 5 | Unauthorized user | Invalid API key |
| Error | 6 | Required bulk array |  |
| Error | 7 | Required bulk data insert format in array |  |
| Error | 8 | Invalid account |  |
| Error | 9 | Unverified account. Please kindly verify your account at easyparcel.com |  |
| Error | 1000 | Missing / Invalid Parameter | If a required parameter is missing or an invalid value is entered, the error will be displayed in the error_detail field. |
| Error | 1002 | Invalid User Account | The user does not have a wallet associated with the relevant country. |
| Error | 1003 | Invalid parcel category, you should refer to Get Parcel Category API | Invalid parcel category, you should refer to Get Parcel Category API |
| Error | 1004 | Invalid collection/ delivery postcode |  |
| Error | 1005 | Invalid collection/delivery state | If the value is "Pulau Penang," an error will occur because our system only accepts state codes. |
| Error | 1006 | Invalid courier | Incorrect Courier code |
| Error | 3001 | Shipment insured | This tracking number has previously purchased insurance through EasyParcel, cannot buy insurance again |
| Error | 3002 | Shipment delivered | The status of this tracking number shipment is "delivered", not allow to buy insurance |
| Error | 3003 | Not under claim coverage | The courier insurance provides coverage for parcel contents up to RM200. However, since you entered a parcel content value of RM100, it does not qualify for claim coverage. |
| Error | 3004 | Only support international/domestic shipment | For example, Fedex only supports international shipments to buy insurance |
| Error | 3005 | No Cover | If the collection state or delivery location is not within the insurance coverage area, an error message along with a description will be displayed. |
| Error | 9999 | Unknown error | If this error occurs, please contact our support team for assistance. |

Support: WhatsApp EasyParcel API Support — https://api.whatsapp.com/send/?phone=6042023160

Published by EasyParcel Sdn Bhd (1028666-H).
