README

High-reliability RajaOngkir API client and Bagisto shipping method package with full caching, dedupe, retry, cooldown protection, and deterministic rate optimization.

Overview

This package provides a fully production-grade RajaOngkir shipping integration for Bagisto. It includes:

Optimized RajaOngkir API client
Automatic cost caching (15m)
Destination caching (24h)
Lifecycle request dedupe - Retry + exponential backoff
Upstream cooldown protection
Normalized rate sorting (cheapest-first or ETA-first logic)
Bagisto-compatible shipping method service
Comprehensive logging with trace IDs

Features

1. Reliable Client

HTTP retry with incremental delay
429/5xx cooldown enforcement
Fail-soft mode during cooldown
Structured logging (request, success, failure, exception)
Normalized request validation
Deterministic caching
Lifecycle dedupe to prevent duplicate processing

2. Shipping Rate Optimizer

Remove duplicate courier services by ETA bracket
Select lowest price per ETA per courier
Global sort (cheapest → ETA → deterministic tie-breaker)

3. Bagisto Integration

Drop-in service provider
Configurable API key
Shipping method class with pre-validation + exception-safe rate fetching
Production-safe calculate() wrapper
Full logging

Requirements

PHP 8.1+
Laravel 10+
Bagisto 2.x

Installation

composer require akara/bagisto-rajaongkir

Usage

After installing and configuring the RajaOngkir shipping package, follow these steps to enable and use it in Bagisto.

1. Enable Shipping Method in Admin Panel

Log in to your Bagisto admin panel.
Navigate to Configure → Sales → Shipping Methods.
Locate RajaOngkir Shipping in the list.
Set Status to Active.
Configure additional options:
- Origin City – the shipping origin for your store.
- Enabled Couriers – select couriers supported by RajaOngkir.
- Rate Sorting – choose Cheapest First or Fastest ETA First.
Save changes.

2. Checkout Usage

Once enabled, RajaOngkir shipping rates will automatically appear on the checkout page for eligible destinations. Calculation is automatic and based on:

Cart Contents: weights and quantities of items in the cart.
Origin & Destination: origin city from admin config, destination from customer shipping address.
RajaOngkir API: fetches live rates.
Optimization: deduplication, caching, and global rate sorting.

Rates are:

Cached for 15 minutes (costs) and 24 hours (destination info).
Deduplicated by courier and ETA.
Sorted according to the selected rate optimization logic.

3. Logs & Troubleshooting

All API requests are logged with structured trace IDs:

Additionnal Information

Rate Optimization Logic

Step 1: Normalize ETA window

Step 2: Deduplicate per Courier

Step 3: Global Sort

Cheapest price
Fastest ETA
Deterministic fallback by courier code

Logging

All requests include structured logs.

Caching & Dedupe

Destination cache: 24h
Cost cache: 15m
API cooldown: 60s

License

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

akara / bagisto-rajaongkir

Maintainers

Details