Shipping

Hoikka supports multiple shipping providers with a unified interface.

Shipping Flow


1. Customer enters address
2. Fetch available shipping rates
3. Customer selects shipping method
4. Create shipment after payment
5. Track shipment status

Getting Rates


const rates = await shippingService.getAvailableRates(order);
 
// Returns available options
[
	{
		id: "flat_rate",
		name: "Standard Shipping",
		price: 590,
		estimatedDeliveryDays: 5
	}
];

Setting Shipping Method


await shippingService.setShippingMethod(orderId, methodId, rateId, price);

Creating Shipment

After order is confirmed:


const shipment = await shippingService.createShipment(order);
// Returns: { trackingNumber: 'FLAT_0000000123', metadata: { ... } }

Tracking


const status = await shippingService.trackShipment(orderId);
// Returns: 'in_transit' | 'delivered' | etc.

Shipping States

State	Description
`pending`	Awaiting shipment creation
`shipped`	Shipment created, in transit
`in_transit`	Package is being delivered
`delivered`	Package delivered

Built-in Provider

Flat Rate

A simple flat-rate provider ships with Hoikka for development and demos. It returns a single “Standard Shipping” rate at a fixed price.

To swap in a real carrier, implement the ShippingProvider interface and register it (see Providers).

Adding Shipping Methods

Configure in admin or database:


// shipping_methods table
{
  code: 'flat_rate',
  name: 'Standard Shipping',
  description: 'Flat rate standard delivery',
  active: true
}