Skip to main content

Device Shipping Policy From Makassar

This document is the internal reference for shipping payment terminal devices from Makassar to merchants. The focus is the business and operational policy, not the detailed SQL design.

Companion document:

Goal​

The main goals of this policy are to:

  • ensure every device shipment has a shipping cost that can be decided consistently
  • limit courier partnerships so that rate negotiations, tracking, and complaints are more controlled
  • hide courier-partner complexity from the merchant
  • prepare a data foundation so that shipping rates can be managed as a reference master

Scope​

This policy covers:

  • primary shipping origin: Makassar
  • shipped goods: payment terminal devices and their accessories
  • shipping destinations: all active merchants within the operational coverage
  • merchant-visible cost: only shipping cost and optionally arrival estimate

Out of scope for this document:

  • per-courier commercial contract negotiation
  • procurement device landed-cost calculation
  • final endpoint design and final SQL migration

Core Principles​

  • The merchant does not pick the courier.
  • The merchant does not see the courier partner name or partner service code.
  • The internal system picks the courier based on priority, coverage, weight, and available rate.
  • Shipping costs must be auditable and have a clear validity period.
  • The shipping decision must remain executable even when the primary partner is unavailable.

Courier Partner Strategy​

The partner model used:

  • 1 primary courier
  • 2 backup couriers

Why this model:

  • simpler operations
  • clearer fallback
  • more focused corporate rate negotiations
  • easier SLA and complaint control

Partner usage order:

  1. primary partner
  2. backup 1
  3. backup 2

The merchant-facing partner remains hidden. Partner names are only used for internal admin, fulfillment, audit, and cost reconciliation needs.

Shipping Mode Policy​

Sulawesi​

For destinations within Sulawesi:

  • prioritize road/cargo
  • regular is only used when operational policy requires it or cargo is not available

Reasoning:

  • the origin is in Makassar
  • the road/cargo path is more suitable for devices and accessories
  • shipping costs are usually more controlled for merchant shipping volume

Outside Sulawesi​

For destinations outside Sulawesi:

  • allow regular or cargo
  • the final decision is determined by shipment weight and partner coverage

Reasoning:

  • not every destination is realistically served by a pure road route from Makassar
  • some destinations require a regular or multi-modal distribution pattern from the partner

Internal Service Categories​

On the system side, the displayed services are limited to:

  • regular
  • cargo

Notes:

  • cargo is the internal category for large or heavy items, or shipments prioritized via the road/cargo lane
  • partner service-name details such as JTR, GOKIL, or other service codes are not exposed to the merchant

Merchant Experience​

Information visible to the merchant:

  • shipping cost
  • arrival estimate when available
  • shipment origin Makassar

Information that must not be visible to the merchant:

  • courier name
  • partner fallback order
  • partner service code
  • internal coverage rules
  • the internal reason a particular partner was chosen

Service Selection Rules​

Initial system rules:

  1. identify the destination city/regency
  2. check whether the destination is in Sulawesi or outside Sulawesi
  3. determine the allowed internal service based on region
  4. check shipment weight or profile
  5. choose the primary partner if coverage and rate are available
  6. on failure, switch to backup 1
  7. on continued failure, switch to backup 2

Minimum fallback conditions:

  • partner coverage unavailable
  • no active rate found
  • partner suspended
  • the required internal service is not supported by that partner

Weight and Service Eligibility Rules​

The final weight rules can still be refined, but this document sets initial principles:

  • a single device or a light package may use regular if coverage is available
  • larger device quantities or higher-volume packages are prioritized to cargo
  • if the destination is within Sulawesi, cargo is the operational default as long as coverage is available

The final weight threshold value will be set in a follow-up implementation document so as not to lock numbers too early before complete rate data is available.

Rate Data Foundation​

Rates must be stored as a master reference, not hardcoded in the application.

Rate data principles:

  • based on origin -> destination city/regency
  • can be differentiated per partner and internal service
  • has an effective date
  • can be activated or deactivated
  • can store partner priority and coverage

Runtime Snapshot​

When a shipment or shipping order is created:

  • the system must take the active rate effective at that time
  • the chosen shipping cost must be saved as a runtime snapshot
  • the final partner used may be saved internally at runtime but must not be shown to the merchant

The goals are:

  • future rate changes do not alter historical orders
  • shipping cost audit remains consistent

Operational Ownership​

Minimum owners to be defined:

  • Ops / Fulfillment: coverage, fallback rules, partner activation
  • Finance / Commercial: rate validation and price changes
  • Engineering: data model, runtime integration, auditability

Rate changes must not directly overwrite without a trace. There must be a validity-period mechanism, active status, and change metadata.

Risks to Manage​

  • too many partners from the start makes operations hard to control
  • rates without validity periods will hinder audit
  • exposing courier names to merchants makes merchant expectations harder to manage
  • not storing the shipping snapshot will cause historical orders to change when rates are updated

Deliverables After This Document​

Once this policy is approved, the next stages are:

  1. finalize the reference data design in db_reference
  2. determine the seed structure for primary and backup partners
  3. define city/regency coverage rules
  4. define the regular vs cargo service threshold
  5. design the runtime integration into db_kesles_merchant
  6. prepare the SQL migrations and initial seeds

Status​

Current status: draft for implementation planning