2026-03-28_order-commission-widget-stripe-fees

Imported from PabloJVelez/private-chef-template (.devagent/workspace/tasks/completed/2026-03-28_order-commission-widget-stripe-fees/AGENTS.md). Install upstream with npx skills add PabloJVelez/private-chef-template --skill 2026-03-28_order-commission-widget-stripe-fees. Copyright stays with the author.

Order Commission Widget — Stripe Processing Fees Line

• Owner: PabloJVelez
• Last Updated: 2026-03-28
• Status: Complete
• Task Hub: .devagent/workspace/tasks/completed/2026-03-28_order-commission-widget-stripe-fees/

Summary

Extend the Medusa admin order payout summary implemented in apps/medusa/src/admin/widgets/order-commission-widget.tsx. The widget already shows platform commission and chef take-home. The goal is to add a line item for Stripe processing fees so the breakdown reconciles (gross → fees → platform commission → chef net, or an equivalent equation that is explicit and correct).

Business context: Payments use Stripe Connect (connected account). Processing fees are incurred on the platform side, but the product intent is to pass those fees through to the connected account (chef)—so the admin UI should reflect that fee as something that reduces what the chef ultimately receives (or otherwise makes the numbers add up in a way operators can trust).

Key Decisions

• [2026-03-28] Clarification (see clarification/2026-03-28_initial-clarification.md): v1 shows estimated Stripe processing fees only (provider formula); hide the row when pass-through is off; label Stripe processing fees; platform commission row = net of that estimate when pass-through on; persist fee/flag on payment.data for admin.

Progress Log

• [2026-03-28] Event: Task hub scaffolded via devagent new-task; ready for clarification, research, and planning.
• [2026-03-28] Event: Research packet — research/2026-03-28_stripe-processing-fee-line-order-widget.md (provider gross-up, persistence gaps, Balance Transaction vs estimate, per-line inconsistency).
• [2026-03-28] Event: Clarification session started — clarification/2026-03-28_initial-clarification.md (Round 1: fee source, pass-through-off UX, copy).
• [2026-03-28] Event: Clarification complete — Round 1 answers 1A, 2A, 3A; packet status Complete; ready for create-plan.
• [2026-03-28] Event: Plan created — plan/2026-03-28_order-commission-widget-stripe-fees.md (4 implementation tasks: util/types, provider persistence + per-line gross-up, medusa-config/env, admin widget).
• [2026-03-28] Event: Implemented — estimate-stripe-processing-fee.ts, provider payoutAdminFieldsForAmount + per-line gross-up, medusa-config / .env.template, order-commission-widget.tsx; removed provider console.log; yarn workspace medusa build passed.
• [2026-03-28] Event: Follow-up UX — payout rows show amounts only (no commission “math” sublabels); removed platform-commission-sublabel plumbing and Stripe “Estimated” sublabel.
• [2026-03-28] Event: Task moved to completed. Updated all status references and file paths from active/ to completed/ throughout task directory.

Implementation Checklist

• Fee source for v1: estimated fee on payment.data (stripe_processing_fee_estimate, pass_stripe_fee_to_chef); no browser Stripe calls.
• Breakdown math: charged → optional Stripe fees (est.) → platform commission (net) → chef take-home = gross − application_fee_amount.
• Provider persists fields on initiate/authorize/capture/retrieve/update (Connect).
• Admin widget conditional row + net platform commission.
• [~] Manual admin spot-check with PASS_STRIPE_FEE_TO_CHEF=true / false — optional in ops; implementation verified via build.

Open Questions

• Fee timing / actual vs estimate — Resolved: v1 = estimate at capture; no async “pending” for actual fees.
• Copy — Resolved: neutral Stripe processing fees; no “passed through” in the label.
• Do any orders use non–Stripe Connect providers where this line should be hidden? — Unchanged: widget already scoped to stripe-connect payment rows only.

References

• [2026-03-28] apps/medusa/src/admin/widgets/order-commission-widget.tsx — Payout summary widget.
• [2026-03-28] .devagent/workspace/tasks/completed/2026-03-20_admin-order-commission-widget/ — Prior task: commission visibility, provider data fields (application_fee_amount), admin zones, research packet.
• [2026-03-28] .devagent/workspace/tasks/active/2026-03-09_port-stripe-connect-and-admin-onboarding/ — Stripe Connect port and admin onboarding context.
• [2026-03-28] .devagent/workspace/product/mission.md — Client template for private chefs; admin transparency supports repeatable onboarding.
• [2026-03-28] .devagent/workspace/product/roadmap.md — Foundation includes Stripe; payout clarity fits Horizon 1–2.
• [2026-03-28] plan/2026-03-28_order-commission-widget-stripe-fees.md — Implementation plan (tasks 1–4).
• [2026-03-28] clarification/2026-03-28_initial-clarification.md — Requirements (complete).
• [2026-03-28] research/2026-03-28_stripe-processing-fee-line-order-widget.md — Fee line options (estimate vs Balance Transaction), passStripeFeeToChef behavior, persistence recommendations.
• [2026-03-28] .devagent/AGENTS.md — Workflow roster (research, create-plan, implement-plan).
• [2026-03-28] [TEMPLATE MISSING] Workflow referenced .devagent/core/templates/task-agents-template.md; this repo uses completed-task AGENTS.md pattern.

Next Steps

Task archived in completed/. Further product tweaks can open a new task hub if needed.