Shopee Margin Guard

#Overview

A net-margin calculator built for Indonesian Shopee sellers (UMKM) who are about to get squeezed by a stacked set of 2026 cost changes: the January admin-fee increase (up to 10%), the Gratis Ongkir Ekstra service fee (effective 2 May 2026), and the seller-shared return shipping cost that starts 1 June 2026 (up to Rp10.000 round-trip, even when a buyer simply changes their mind). That last one is the change most sellers never see coming.

The problem is that many products that look profitable quietly turn loss-making once all of that is applied, and most sellers never find out which ones. Upload a catalog (CSV or Excel) and the tool computes the real net margin per SKU after every 2026 deduction, flags the loss-makers in red, shows the total rupiah leaking each month, and suggests a corrected price to hit a target margin. For imported goods it also models what a weakening rupiah does to that margin.

The UI is in Bahasa Indonesia (that’s the audience); the code and docs are in English.

#Challenge

The 2026 fee stack is genuinely confusing. Rates arrive from scattered news sources with different effective dates and category tiers, and the typical seller computes “margin” as price minus cost, missing the platform fees and the brand-new return-cost exposure entirely.

The tool had to:

• Model every 2026 rate from a single, sourced configuration: admin fee per category, order-processing fee, Gratis Ongkir Ekstra (capped), pre-order surcharge, and the new return-cost share, each with its effective date.
• Ingest a real seller’s catalog from CSV or Excel, accepting both Indonesian and English column headers.
• Solve break-even and target-margin prices numerically, because the Gratis Ongkir Ekstra cap makes net margin non-linear, so a naive closed-form price is wrong exactly when the cap binds.
• Ship as a shareable web app a non-technical seller can actually use, then export the result.

#Solution

#Fee model as the single source of truth

Every 2026 rate lives in one sourced config (fee_config.yaml), each quoted with its source and effective date in a companion FEE_MODEL.md. The engine reloads rates at runtime, so when Shopee changes a fee it’s a one-line config edit, not a code change or a redeploy of logic. Rates that couldn’t be fully verified are explicitly flagged UNVERIFIED with conservative placeholders, so the model is honest about what’s confirmed versus assumed.

#The margin engine

For each SKU it computes net price after seller-funded vouchers, subtracts the full Shopee fee stack (category admin fee, order-processing, Gratis Ongkir Ekstra when opted in, pre-order surcharge), subtracts COGS, and subtracts the expected return cost (return-rate times the capped per-unit exposure). For imported goods, COGS is recomputed from a USD cost and an FX rate, with a sensitivity table at current, +5%, and +10% FX. Break-even and target-margin prices are solved by bisection, which stays correct even when the Gratis Ongkir Ekstra cap binds.

#Pure-Python, deploy-anywhere

Ingestion uses the standard-library csv module plus openpyxl, so there is no pandas and no C build. The whole thing serves with Waitress and ships with a Dockerfile and a Procfile, so it deploys on a free Render, Railway, or Fly tier. State is per-browser-session, so several sellers can use one shared demo link at once without clobbering each other.

#The workflow

You set the assumptions (target margin, default return rate, and an FX rate that’s fetched live), load a catalog (upload your own, or try the built-in 8-SKU sample), and get a dashboard with a plain-language auto-analysis of what’s bleeding and why, a 0 to 100 margin health score, a per-product margin chart, a sortable per-SKU ledger with loss-makers in red (click a row for the fee breakdown and FX table), a repricing view, and CSV or printable-HTML (to PDF) export.

#Results

• 32 tests, including 4 hand-calculated worked examples. The arithmetic is verified against pen-and-paper scenarios, not assumed. The full math is documented in WORKED_EXAMPLES.md.
• Deploy-ready. Dockerfile, Procfile, and Waitress; a non-technical seller can be sent a link and just press Run.
• Updatable by design. When Shopee changes a rate (and it changes often), the fix is a config edit plus a sourced quote update, with zero changes to the calculation logic.
• Honest about its limits. A documented red-team / self-review section lists the assumptions (restockable returns, journalistic admin-fee tiers) and the handful of UNVERIFIED rates, each with a conservative default and a TODO.

#How the margin is computed (the core)

net price        = harga_jual × (1 − voucher%)
net margin (Rp)  = net price − Shopee fees − COGS − expected return cost
net margin (%)   = net margin / harga_jual × 100

Where Shopee fees = category admin fee (on net price) + order-processing + Gratis Ongkir Ekstra (if opted in, capped) + pre-order surcharge, expected return cost = return_rate% × capped per-unit return exposure, and imported COGS = USD × FX × (1 + import overhead). Break-even and target-margin prices are solved numerically rather than in closed form, because the Gratis Ongkir Ekstra cap makes the relationship non-linear.

#Why these choices

• Pure Python, no pandas. Deploys on free tiers without a native build, and the dependency surface stays tiny.
• Rates in config, not code. Shopee changes fees regularly, and keeping every rate in one sourced YAML means the logic never has to move.
• Bisection for pricing. The Gratis Ongkir Ekstra cap makes net margin non-linear, so a closed-form price would be wrong precisely when the cap is active. Numerical solving stays correct in every case.