Vendure RajaOngkir Plugin

A comprehensive shipping integration plugin for Vendure e-commerce framework that integrates with RajaOngkir/Komerce API for Indonesian shipping cost calculation.

Features

• 🚚 Multi-Courier Support - JNE, J&T, SiCepat, POS Indonesia, TIKI, Lion Parcel, Ninja Express, AnterAja, ID Express, SAP Express, Wahana
• 📍 Destination Search - Search by city, district, subdistrict, or postal code
• 💰 Real-time Shipping Costs - Calculate accurate shipping costs based on weight and destination
• 🔌 Shipping Calculator - Built-in Vendure shipping calculator for automatic pricing
• 🎯 GraphQL API - Shop and Admin API extensions for easy integration
• ⚡ Caching - Built-in caching for improved performance
• 🌐 Bilingual - English and Indonesian language support

Installation

From npm (after publishing)

npm install @rendure/rajaongkir-plugin

From GitHub

npm install YOUR_USERNAME/vendure-rajaongkir-plugin

Local Installation (for development)

cd /path/to/vendure-rajaongkir-plugin
npm pack
cd /path/to/your-vendure-project
npm install /path/to/vendure-rajaongkir-plugin/rendure-rajaongkir-plugin-1.0.0.tgz

Configuration

1. Get RajaOngkir API Key

Sign up at RajaOngkir/Komerce to get your API key.

2. Find Your Origin Location ID

Use the destination search API to find your warehouse/store location ID:

query {
  rajaOngkirSearchDestinations(search: "Jakarta Pusat") {
    id
    label
    cityName
    districtName
  }
}

3. Configure the Plugin

In your vendure-config.ts:

import { RajaOngkirPlugin } from '@rendure/rajaongkir-plugin';

export const config: VendureConfig = {
  // ... other config
  plugins: [
    RajaOngkirPlugin.init({
      apiKey: process.env.RAJAONGKIR_API_KEY!,
      defaultOriginId: 6186, // Your warehouse location ID
      enabledCouriers: ['jne', 'jnt', 'sicepat'], // Optional, defaults to these 3
      defaultWeight: 1000, // Optional, default weight in grams
      cacheDuration: 300000, // Optional, cache duration in ms (default: 5 minutes)
      enableLogging: true, // Optional, enable debug logging
    }),
    // ... other plugins
  ],
};

Usage

GraphQL Shop API

Search Destinations

query SearchDestinations {
  rajaOngkirSearchDestinations(
    search: "Bandung"
    limit: 10
  ) {
    id
    label
    provinceName
    cityName
    districtName
    subdistrictName
    zipCode
  }
}

Calculate Shipping Costs

query CalculateShipping {
  rajaOngkirCalculateShipping(
    destinationId: 6186
    weight: 1000
  ) {
    id
    courierCode
    courierName
    service
    description
    cost
    etd
  }
}

Get Available Couriers

query AvailableCouriers {
  rajaOngkirAvailableCouriers {
    code
    name
    description
  }
}

GraphQL Admin API

All Shop API queries are available, plus:

Clear Cache

mutation ClearCache {
  rajaOngkirClearCache
}

Shipping Calculator

The plugin automatically registers a shipping calculator that you can use in the Vendure Admin UI:

1. Go to Settings → Shipping Methods
2. Create a new shipping method
3. Select RajaOngkir Shipping Calculator
4. Configure:
   • Courier Code: Select the courier (jne, jnt, sicepat, etc.)
   • Service Type: Select the service (REG, YES, OKE, EZ, etc.)
   • Fallback Price: Price to use if API fails (in cents)

The calculator will:

• Automatically look up the destination from the shipping address
• Calculate the total weight from order items
• Fetch real-time shipping costs from RajaOngkir API
• Return the price in Vendure's currency format

Configuration Options

| Option | Type | Required | Default | Description | |--------|------|----------|---------|-------------| | apiKey | string | ✅ | - | Your RajaOngkir API key | | defaultOriginId | number | ✅ | - | Origin location ID (from search API) | | enabledCouriers | CourierCode[] | ❌ | ['jne', 'jnt', 'sicepat'] | List of enabled couriers | | defaultWeight | number | ❌ | 1000 | Default weight in grams if product has no weight | | cacheDuration | number | ❌ | 300000 | Cache duration in milliseconds | | enableLogging | boolean | ❌ | false | Enable debug logging |

Supported Couriers

• JNE - Jalur Nugraha Ekakurir
• J&T - J&T Express Indonesia
• SiCepat - SiCepat Ekspres
• POS - PT Pos Indonesia
• TIKI - Titipan Kilat
• Lion Parcel - Lion Parcel Indonesia
• Ninja Express - Ninja Van Indonesia
• AnterAja - AnterAja Logistics
• ID Express - ID Express Logistics
• SAP Express - SAP Express Courier
• Wahana - Wahana Prestasi Logistik

Product Weight Configuration

The plugin calculates shipping costs based on product weight. You can set weight in two ways:

Option 1: Custom Field (Recommended)

Add a weight custom field to your product or variant:

// In vendure-config.ts
customFields: {
  ProductVariant: [
    {
      name: 'weight',
      type: 'int',
      label: [{ languageCode: LanguageCode.en, value: 'Weight (grams)' }],
    },
  ],
}

Option 2: Default Weight

If no weight is set, the plugin uses the defaultWeight from configuration (default: 1000g).

Troubleshooting

"No shipping options found"

• Verify your API key is correct
• Check that the destination ID is valid
• Ensure the courier is enabled in your configuration
• Check API logs for detailed error messages

"Destination not found"

• The shipping address postal code may not be in RajaOngkir database
• Try searching for the destination manually and storing the ID
• Consider adding a custom field to store the destination ID

Build Errors

If you encounter TypeScript errors during build:

npm install --save-dev @vendure/core typescript
npm run build

Development

Building the Plugin

npm install
npm run build

Watch Mode

npm run watch

Testing Locally

npm pack
cd /path/to/your-vendure-project
npm install /path/to/vendure-rajaongkir-plugin/rendure-rajaongkir-plugin-1.0.0.tgz

Publishing

To GitHub

git add .
git commit -m "Initial commit"
git branch -M main
git remote add origin https://github.com/YOUR_USERNAME/vendure-rajaongkir-plugin.git
git push -u origin main

Then install in your project:

npm install YOUR_USERNAME/vendure-rajaongkir-plugin

To npm

npm login
npm publish --access public

API Reference

For detailed API documentation, see the RajaOngkir API Documentation.

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues and questions:

• Open an issue on GitHub
• Check the Vendure documentation
• Visit RajaOngkir documentation