Dynamic Indonesian shipping depends on two separate contracts: the host resolves a customer address to provider-compatible region metadata, then a quote provider prices the complete parcel. Keep those boundaries explicit so region data can change without rewriting the commerce core.
Import region data
@adocommercekit/id does not bundle Indonesian administrative-region rows. The host must obtain and maintain a source whose distribution and update terms it has reviewed.
pnpm add @adocommercekit/id
node ace configure @adocommercekit/id
node ace migration:run
node ace commerce:id:regions-import --file ./data/indonesia-regions.jsonKeep the source file, license decision, retrieval date, checksum, and import result in the merchant’s controlled release evidence. Re-import through the command rather than editing region tables manually.
The configure hook publishes reviewable host-owned validator, controller, and route stubs. Typeahead accepts only a string q (not arrays or objects) and escapes SQL wildcard characters so % and _ are literal search input. The published search route enforces 60 requests/minute/IP per application process. Deploy a shared edge rate limit for distributed deployments; the in-process limit is not a cluster-wide quota. Before exposing typeahead or validation routes, add host authorization where needed, bound input length, and return only the fields checkout needs.
Address rules
Use validateIndonesiaAddress() only for countryCode: "ID". Preserve the selected region identifiers in address metadata so the quote driver does not have to infer locations from display text.
A production checkout should collect:
- recipient name and a normalized Indonesian phone number;
- street and building detail;
- province, kabupaten/kota, kecamatan, and postal code at the precision required by the provider;
- provider destination identifiers under stable host metadata; and
- delivery notes separately from the canonical address.
Never accept a browser-provided shipping price. The server must request a quote from the stored address and parcel, sign the selected quote, and verify that selection during checkout.
Biteship: rates and fulfillment
pnpm add @adocommercekit/biteship
node ace configure @adocommercekit/biteship
node ace migration:runimport { biteship, biteshipPreparationStore } from "@adocommercekit/biteship"
const biteshipDriver = biteship({
apiKey: env.get("COMMERCE_BITESHIP_API_KEY"),
origin: {
areaId: env.get("COMMERCE_BITESHIP_ORIGIN_AREA_ID"),
address: "Warehouse address",
contactName: "Operations",
contactPhone: "+6281234567890",
},
couriers: ["jne", "jnt", "sicepat"],
preparationStore: biteshipPreparationStore(),
webhookSecret: env.get("COMMERCE_BITESHIP_WEBHOOK_SECRET"),
})
shipping: {
quoteProviders: { biteship: biteshipDriver },
},
fulfillment: {
providers: { biteship: biteshipDriver },
}Biteship includes parcel value, weight, dimensions, destination, COD, insurance, currency, and provider options in quote/cache identity. Rates require IDR and an Indonesian destination, with non-negative IDR declared values. cacheTtlSeconds defaults to 60 and cannot exceed 60; the rate cache defaults to a 1,000-entry LRU, configurable through cacheMaxEntries. Quote expiry is separately controlled by quoteTtlSeconds (default 60).
Durable preparation and uncertain creation
Fulfillment requires a selected courier:service and a durable preparationStore; quotes alone do not require the journal. Configure publishes the preparation-journal migration, so run migrations before preparing shipments. The journal claims the order-number reference before posting and persists accepted responses before validating the waybill.
Preparation requires an IDR order; COD/insurance currency must match that order, and the COD collect amount must equal its grand total.
If creation is uncertain (including a timeout or process restart), the driver does not automatically post another order. An operator must locate/retrieve the provider order and call DatabaseBiteshipPreparationStore.resolve(reference, response) with the matching reference_id and provider order ID. Call confirmNotCreated(reference) only after Biteship confirms that no order was created; it allows a subsequent creation attempt. Never interpret a timeout as proof that creation failed. Biteship’s documented order API does not expose a reference-ID lookup endpoint, so reconciliation does not depend on an undocumented list API.
Tracking webhooks
Configure publishes the raw-body POST route /api/commerce/webhooks/biteship. In Biteship, configure the custom webhook header key x-commerce-biteship-secret with the value from COMMERCE_BITESHIP_WEBHOOK_SECRET. Keep the route outside browser CSRF protection and preserve the exact body; programmatic hosts may instead pin a webhookVerifier. Verification fails closed without a matching verifier or configured secret.
order.status applies idempotent core tracking transitions: cancelled cancels, disposed fails delivery, and on_hold changes no tracking state. Unknown event types/statuses remain durable unhandled inbox events rather than fabricated transitions. order.price stores biteshipCostAdjustment shipment metadata without changing the customer order total. order.waybill_id updates waybill/tracking metadata.
For upgrades, loadBiteshipUpgradeArtifacts() from @adocommercekit/biteship/upgrade supplies reviewable host-publication artifacts. Review the published config, controller, and routes during commerce:upgrade; do not overwrite merchant webhook customizations blindly.
RajaOngkir: rates and available tracking
pnpm add @adocommercekit/rajaongkir
node ace configure @adocommercekit/rajaongkirimport { rajaOngkir } from "@adocommercekit/rajaongkir"
shipping: {
quoteProviders: {
rajaongkir: rajaOngkir({
apiKey: env.get("COMMERCE_RAJAONGKIR_API_KEY"),
originId: env.get("COMMERCE_RAJAONGKIR_ORIGIN_ID"),
couriers: ["jne", "jnt", "sicepat"],
}),
},
}Destinations need rajaOngkirDestinationId metadata—directly or under metadata.indonesia—or a host resolveDestination callback. Rates require IDR, an Indonesian address, and positive aggregate parcel weight.
RajaOngkir explicitly reports waybill creation, fulfillment, COD, and insurance as unsupported. Do not emulate those capabilities. Pair it with a separate fulfillment process only when the host can represent that boundary honestly.
Tracking sends awb and courier as query parameters, not a request-body transport. It uses delivery_status/summary and the latest manifest timestamp interpreted in Asia/Jakarta and normalized to UTC. Only data.delivered === true produces delivered: a depot receipt or a status label alone is not proof of customer delivery.
COD reconciliation and carrier payables
Use IndonesiaLogisticsService.reconcile(contents, { fileName?, actor? }) for the Biteship-aware remittance workflow. CSV imports accept a leading UTF-8 BOM. The journal records line outcomes including settled, duplicate, rto, short, over, unmatched, invalid, and review.
Use COD_RECONCILIATION_SCHEMA (commerce.cod-reconciliation.v2) and the exact header:
schema_version,merchant_id,order_number,carrier,waybill,status,gross_amount,fee_amount,adjustment_amount,net_amount,currency,referenceRows require the configured merchant ID, IDR, delivered or rto, non-negative gross/fee amounts, and net_amount = gross_amount - fee_amount + adjustment_amount. Settlement compares gross, not net remittance, to the order grand total.
Only a matching pending_cod order can be settled. If settlement returns review-required, the line is recorded as review without creating a successful remittance-import record; do not treat that review as cash received and finalized. Short/over payments, missing or ambiguous orders, and a waybill belonging to another order require operator investigation.
Submitting the same completed file returns its existing batch. Resubmitting a failed file resumes that batch and skips already journaled line numbers, rather than reapplying them. An RTO line calls the core returned-to-sender shipment transition. If that order was previously settled, it is recorded for financial review: reconcile the refund or carrier credit separately rather than reversing funds implicitly.
IndonesiaLogisticsService.carrierPayables("YYYY-MM") exports fees, adjustments, and payable amounts (fee - adjustment) grouped by carrier and currency from settled/rto lines in completed batches, using the line creation month. In the published admin panel, GET <COMMERCE_PANEL_PREFIX>/id/logistics/payables?month=YYYY-MM downloads the CSV and requires the commerce.payments.reconcile ability. Use the configured panel prefix, not an assumed payment-provider webhook path.
Operational checklist
- Confirm every sellable variant has weight and any dimensions required by enabled couriers.
- Verify origin IDs and courier codes in the provider environment used by the merchant.
- Cache quotes for no longer than the provider allows; Biteship caps the rate-cache TTL at 60 seconds.
- Expire signed selections when address, parcel, currency, provider options, or cart contents change.
- Reconcile shipment state transitions and webhook retries against the host order timeline.
- Keep API keys, raw addresses, recipient phone numbers, and full provider payloads out of logs.
Continue
- Configure payments for Indonesia.
- Review IDR and PPN evidence.
- Learn how generic state machines and workflows protect fulfillment transitions.
- Use the operations guide before enabling webhooks and queues.