Twill Brain

#900 Add 'bin_fee' to Partner table & update Commission Calc

1 min read

#900 — Add ‘bin_fee’ to Partner table & update Commission Calc

Repo: Twill-AI/facade State: closed | Status: done Assignee: meliascosta, nadddder

Created: 2026-01-06 · Updated: 2026-01-23

Description

We need to track a bin_fee for every partner and deduct this cost from their monthly commission payouts. This fee is calculated against their total processing volume.

1. Partner Entity

  • Add bin_fee_low_risk, bin_fee_med_risk, bin_fee_high_risk to DbPartner
  • Update POST/PUT master/partner endpoints to accept these fields
  • Add migration (Consider previous manual changes in prod on subset of partners)

2. Commission DTOs

  • Add to MerchantCommissionsReportResponse:
    • gross_commission (rename current total_commission)
    • bin_fee_deduction
    • net_commission (new total after deduction)
  • Add to MerchantCommission (per-merchant breakdown):
    • bin_fee_rate
    • bin_fee_deduction
    • net_commission

3. Commission Calculation (commissions_helper.py)

  • Update SQL to calculate: bin_fee_deduction = volume × bin_fee_{risk}
  • Update all commission queries to return gross/net breakdown
  • Ensure trend data shows net commission

4. API Response Changes

  • Master commission summary shows gross, bin_fee, net
  • Per-merchant breakdown includes bin_fee details
  • Create a frontend ticket if not backward compatible (UI should show the same for partners, just used adjusted numbers)
  • Add bin fees to the Master Trends Endpoint

Notes

Add implementation notes, blockers, and context here

Add wikilinks to related people, meetings, or other tickets

Graph View