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);
 
// Aggregates rates from all active providers; each rate is stamped with the
// shipping method it came from
[
	{
		id: "flat_rate",
		name: "Standard Shipping",
		price: 590,
		estimatedDeliveryDays: 5,
		description: "Standard delivery",
		methodId: 1,
		methodCode: "flat_rate"
	}
];

Setting Shipping Method


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

Creating Shipment

After order is confirmed:


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

The tracking number is saved on order_shipping; the status stays pending until it is updated manually (updateShippingStatus) or by tracking.

Tracking


const status = await shippingService.trackShipment(orderId);
// Returns: 'in_transit' | 'delivered' | etc., or null when there is no
// tracking number or the provider does not support tracking

Shipping States

State	Description
`pending`	Default, also after shipment creation
`shipped`	Manually marked as shipped
`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
}