README

This package provides a simple and easy-to-use Laravel wrapper for the RajaOngkir Komerce API. It supports two methods of address lookup: hierarchical step-by-step selection and direct search with autocomplete functionality.

Requirements

Requirement	Version
PHP	^8.2
Laravel	^11.0, ^12.0, or ^13.0

Installation

You can install the package via composer:

composer require blissjaspis/laravel-rajaongkir-komerce

You must publish the configuration file with:

php artisan vendor:publish --tag=rajaongkir-komerce-config

Or using the provider:

php artisan vendor:publish --provider="BlissJaspis\RajaOngkir\Providers\RajaOngkirServiceProvider" --tag="config"

Add the following to your .env file:

RAJAONGKIR_API_KEY=your-api-key
RAJAONGKIR_BASE_URL=https://rajaongkir.komerce.id/api/v1

# Optional
RAJAONGKIR_TIMEOUT=30
RAJAONGKIR_RETRY_TIMES=0
RAJAONGKIR_RETRY_SLEEP=100
RAJAONGKIR_FAKE=false

Set RAJAONGKIR_FAKE=true in local development to stub all API responses without calling Komerce.

The package is auto-discovered via Laravel's package discovery. No manual registration is required.

Usage

There are two ways to use Rajaongkir-Komerce:

Step-by-step method. This was the old method before Komerce acquired Rajaongkir and changed the API.
Direct Search. This is the latest method used by Komerce after they acquired Rajaongkir.

For existing users whose data is still using the old method, you can continue using method 1.

This package supports 2 ways to access RajaOngkir data:

Step-by-step location lookup (province -> city -> district -> subdistrict)
Direct search and shipping cost lookup (search by keyword, then calculate cost)

You can call the API through the facade or Laravel's service container:

use BlissJaspis\RajaOngkir\Facades\RajaOngkir;
use BlissJaspis\RajaOngkir\RajaOngkir as RajaOngkirClient;

// Via Facade (recommended)
$response = RajaOngkir::getProvinces();
$provinces = $response->data;

// Via dependency injection (interface)
use BlissJaspis\RajaOngkir\Contracts\RajaOngkirClient;

public function __construct(private RajaOngkirClient $rajaOngkir) {}

// Or resolve from the container
app(RajaOngkirClient::class)->getProvinces();

API methods return a RajaOngkirResponse object with meta, data, status(), and successful(). Use getListCourier() when you need the static courier list (hardcoded from Komerce documentation — no API endpoint).

RajaOngkir is registered as a singleton in the service container, so the facade and app() resolve the same instance.

Error handling

Failed HTTP requests and API error responses throw BlissJaspis\RajaOngkir\Exceptions\RajaOngkirException:

use BlissJaspis\RajaOngkir\Exceptions\RajaOngkirException;
use BlissJaspis\RajaOngkir\Facades\RajaOngkir;

try {
    $response = RajaOngkir::getProvinces();
} catch (RajaOngkirException $exception) {
    $statusCode = $exception->statusCode;
    $body = $exception->response;
}

Choosing Between Methods

Use Method 1 (Step-by-step) if:

You have existing user data stored in the hierarchical format
You prefer structured location selection with multiple dropdowns
You're migrating from the old Rajaongkir API structure

Use Method 2 (Direct Search) if:

You're building a new application
You want a better user experience with search/autocomplete
You want to simplify your frontend code and reduce API calls
You want to provide international shipping options

Method 2 is recommended for new implementations as it provides a more modern and user-friendly approach.

Method 1: Step-by-Step Location Lookup

Use this method when users select addresses hierarchically.

1. Finding Provinces

$response = RajaOngkir::getProvinces();
$provinces = $response->data;

{
  "meta": {
    "message": "Success Get Provinces",
    "code": 200,
    "status": "success"
  },
  "data": [
    {
      "id": 11,
      "name": "DKI Jakarta"
    },
    {
      "id": 6,
      "name": "Jawa Barat"
    }
    // ... more provinces
  ]
}

2. Finding Cities

$provinceId = 11;
$cities = RajaOngkir::getCity($provinceId);

{
  "meta": {
    "message": "Success Get Cities",
    "code": 200,
    "status": "success"
  },
  "data": [
    {
      "id": 1,
      "name": "Jakarta Pusat"
    },
    {
      "id": 2,
      "name": "Jakarta Selatan"
    }
    // ... more cities
  ]
}

3. Finding Districts

$cityId = 1;
$districts = RajaOngkir::getDistrict($cityId);

{
  "meta": {
    "message": "Success Get Districts",
    "code": 200,
    "status": "success"
  },
  "data": [
    {
      "id": 1,
      "name": "Kemayoran"
    }
    // ... more districts
  ]
}

4. Finding Subdistricts

$districtId = 1;
$subdistricts = RajaOngkir::getSubDistrict($districtId);

{
  "meta": {
    "message": "Success Get Subdistricts",
    "code": 200,
    "status": "success"
  },
  "data": [
    {
      "id": 1,
      "name": "Sumur Batu"
    }
    // ... more subdistricts
  ]
}

Method 2: Direct Search and Cost Lookup

Use this method when users type destination keywords directly, then you calculate shipping.

1. Searching Domestic Destinations

$search = 'sinduharjo';
$limit = 10; // optional
$offset = 0; // optional
$destinations = RajaOngkir::searchDomestic($search, $limit, $offset);

{
  "meta": {
    "message": "Success Get Domestic Destinations",
    "code": 200,
    "status": "success"
  },
  "data": [
    {
      "id": 31555,
      "label": "SINDUHARJO, NGAGLIK, SLEMAN, DI YOGYAKARTA, 55581",
      "subdistrict_name": "SINDUHARJO",
      "district_name": "NGAGLIK",
      "city_name": "SLEMAN",
      "province_name": "DI YOGYAKARTA",
      "zip_code": "55581"
    }
  ]
}

2. Searching International Destinations

$search = 'Malaysia';
$limit = 10; // optional
$offset = 0; // optional
$destinations = RajaOngkir::searchInternational($search, $limit, $offset);

{
  "meta": {
    "message": "Success Get International Destinations",
    "code": 200,
    "status": "success"
  },
  "data": [
    {
      "id": 108,
      "name": "Malaysia"
    }
    // ... more destinations
  ]
}

3. Calculating Domestic Shipping Cost

$origin = 1;
$destination = 108;
$weight = 1000;
$courier = 'jne';
$filter = 'lowest';

$cost = RajaOngkir::getCostDomestic($origin, $destination, $weight, $courier, $filter);

{
  "meta": {
    "message": "Success Calculate Domestic Shipping cost",
    "code": 200,
    "status": "success"
  },
  "data": [
    {
      "name": "Nusantara Card Semesta",
      "code": "ncs",
      "service": "DARAT",
      "description": "Regular Darat",
      "cost": 8000,
      "etd": "6-7 day"
    },
    {
      "name": "Citra Van Titipan Kilat (TIKI)",
      "code": "tiki",
      "service": "ECO",
      "description": "Economy Service",
      "cost": 15000,
      "etd": "5 day"
    }
  ]
}

4. Calculating International Shipping Cost

$origin = 1;
$destination = 108;
$weight = 1000;
$courier = 'jne';
$filter = 'lowest';

$cost = RajaOngkir::getCostInternational($origin, $destination, $weight, $courier, $filter);

{
  "meta": {
    "message": "Success Calculate International Shipping Cost",
    "code": 200,
    "status": "success"
  },
  "data": [
    {
      "name": "Rayspeed Indonesia",
      "code": "ray",
      "service": "Regular Service",
      "description": "Retail",
      "currency": "IDR",
      "cost": 55000,
      "etd": ""
    },
    {
      "name": "Lion Parcel",
      "code": "lion",
      "service": "INTERPACK",
      "description": "Active",
      "currency": "IDR",
      "cost": 65000,
      "etd": "2-3 day"
    }
  ]
}

5. Tracking Waybill

$waybill = 'MT685U91';
$courier = 'jne';

$waybill = RajaOngkir::getWaybill($waybill, $courier);

{
  "meta": {
    "message": "Success Get Waybill",
    "code": 200,
    "status": "success"
  },
  "data": {
    "delivered": true,
    "summary": {
      "courier_code": "wahana",
      "courier_name": "Wahana Prestasi Logistik",
      "waybill_number": "MT685U91",
      "service_code": "",
      "waybill_date": "2024-10-08",
      "shipper_name": "TOKO ALAT LUKIS (08112XXXXXX)",
      "receiver_name": "FIKRI EL SARA (085668XXXXXX)",
      "origin": "",
      "destination": "di Kota Sukabumi",
      "status": "DELIVERED"
    },
    "details": {
      "waybill_number": "MT685U91",
      "waybill_date": "2024-10-08",
      "waybill_time": "11:14:29",
      "weight": "",
      "origin": "",
      "destination": "di Kota Sukabumi",
      "shipper_name": "TOKO ALAT LUKIS (08112XXXXXX)",
      "shipper_address1": "",
      "shipper_address2": "",
      "shipper_address3": "",
    }
    "delivery_status": {
      "status": "DELIVERED",
      "pod_receiver": "FIKRI EL SARA (085668XXXXXX)",
      "pod_date": "2024-10-11",
      "pod_time": "09:26:13"
    },
    "manifest": [
      // ... more manifest
    ]
  }
}

Other Useful Methods

getListCourier() returns a static list of supported courier codes and display names (not an API call):

$couriers = RajaOngkir::getListCourier();

// [
//     'jne' => 'JNE',
//     'sicepat' => 'SICEPAT',
//     'tiki' => 'TIKI',
//     // ...
// ]

API Reference

For comprehensive API documentation including:

Complete method signatures with parameter types
Detailed response structures
Error handling examples
Testing examples
Best practices
Migration guides
Troubleshooting

Please see API-REFERENCE.md for detailed technical documentation optimized for developers and AI assistants.

Testing & Quality

This package uses GitHub Actions for continuous integration: lint runs once, then tests run across PHP 8.2–8.5 and Laravel 11–13.

Command	Description
`composer test`	Run PHPUnit tests
`composer lint`	Syntax check, Pint (dry-run), and PHPStan (level 6)
`composer analyse`	Run PHPStan static analysis only
`composer format`	Auto-format code with Laravel Pint
`composer check`	Run `lint` + `test` (recommended before PRs)

composer check

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

For contribution guidelines and local development setup, see CONTRIBUTING.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

The MIT License (MIT). Please see License File for more information.

blissjaspis / laravel-rajaongkir-komerce

Maintainers

Package info

Statistics

Security