License holders vs the producer who earned the commission

In a lot of agencies, the person whose name is on the carrier paperwork is not the person who wrote the business.

This is not a workaround anyone is embarrassed about; it is how the business is structured. A small number of licensed holders carry the paperwork while newer people, still working toward a licence, actually find and write the business. The agency knows exactly who earned what. The carrier’s files say something else.

Two questions that look like one

Software tends to collapse this into a single question — “which agent is this policy for?” — and that collapse is where the bugs live, because there are two independent questions:

1. Who is on the policy? The licensed holder, as recorded by the source system in the producer field.
2. Who earned the commission? The agency’s answer, which may be someone else entirely.

A model with one agent field per policy can only answer one of them, so it answers the first and silently loses the second.

Two mechanisms, because they are two problems

A flag on the agent record. An agent can be marked as a licence holder who is not an actual producing agent. The platform excludes accounts like this from commission paths structurally — not by relying on their balance happening to be zero, which would depend on the data being tidy. Someone who is both a holder and a producer keeps producing status; the exclusion applies only to holders who are not actual agents.

The distinction matters because the cost of getting it wrong is one-directional. A real producer wrongly excluded goes unpaid and says so within a day. A pure holder wrongly included receives money that belongs to someone else, and the error surfaces at payout time — or later.

A tenant-level switch for manual policy-to-agent mapping. Attribution rules are an agency policy, not a platform default. When the switch is on, newly imported policies do not go straight into the policy table; they wait for an operator to confirm the real producing agent. When it is off, policies import directly and attribution follows the source. Two agencies on the same platform can run entirely different arrangements.

The part that surprises operators

Policy mapping and commission attribution are not the same code path. Commission arrives in the carrier’s commission file, and that file’s attribution follows its own producer field — the holder — regardless of what the mapping queue decided about the policy.

So confirming a policy’s real producer improves what the agency knows about the policy and the client. It does not, by itself, move the commission. Anyone who assumes otherwise will confirm a queue full of policies and wonder why the totals never changed. Correcting commission attribution means correcting it on the commission path.

We consider this worth documenting loudly rather than smoothing over, because a system that quietly made the two look like one would be right more often and unaccountably wrong at exactly the moments that matter.

Refusing to guess

When the platform cannot determine who earned a commission, it does not pick the most likely candidate. It records the relationship as unconfirmed and shows it that way.

An automatic guess here is worse than a pending item. A guess produces a number that looks exactly as authoritative as a correct one, attributed to a specific person, and it gets paid. A pending item produces a queue that somebody has to work — visible cost, no silent error.

Practical notes

• Turning the mapping switch off stops new items from pausing. It does not release the ones already waiting, and it should not: “we turned the feature off” is not the same statement as “these policies are fine without review”.
• If the platform cannot read the switch’s value, the UI treats it as unknown and disables the control, rather than defaulting to off. One click should never be able to silently remove a protection that was on.
• Your mapping decisions live in their own layer, so refreshing source data does not overwrite them. A confirmed attribution stays confirmed.