Upline cascade calculation

Upline cascade credits the people above the triggering collaborator. When a trigger fires, Siren walks the chain upward from the person who caused it and pays each layer at the score you configured for that layer.

How it works

A trigger fires on one collaborator. They made a sale, they hit a metric, whatever the program watches. Upline cascade starts from that collaborator’s position in the bound CollaboratorGroup and walks toward the top.

Layers are 1-indexed and counted from the trigger outward. Layer 1 is the direct upline, one step above the triggering collaborator. Layer 2 is the layer above that. The cap is layer 5.

For each layer the cascade visits, it reads pointsAtLayer{N} from the configured args and credits the collaborator at that layer at that score. Going up, each collaborator has a single parent, so an upline layer always holds exactly one peer, in both a linear chain and a parent-child tree. A layer holding several peers is a downline behavior, where one collaborator can have many children.

The per-layer value is a score, not a dollar amount. It sets each collaborator’s weight, and the program’s incentive turns those weights into the actual payout. Pairing the cascade with a performance-weighted pool splits a reward pool in proportion to the scores, so the layer values decide each person’s share of that pool.

A 0 (or unset) value at any layer stops the cascade right there. If you set pointsAtLayer1: 100, pointsAtLayer2: 50, pointsAtLayer3: 0, the cascade walks two layers and stops. It does not jump over the 0 to look at layer 4.

The triggering collaborator is never credited by an upline cascade. They caused the event, so the payout flows to the people above them.

If an ancestor in the line is suspended or deleted, that layer earns nothing and the cascade keeps climbing to the next ancestor, who is still credited at their own layer’s rate. For example, if the layer-2 grandparent is suspended, layer 2 pays no one, but layer 3 still credits the great-grandparent at the layer-3 score. The skipped layer’s points are not reassigned to anyone else.

If the bound CollaboratorGroup doesn’t expose layers (a flat group, for example), upline cascade has nothing to walk and emits no credits. It fails closed. It emits nothing and never falls back to a single Fixed credit. The picker on the Programs Edit and Distributors Edit screens hides upline cascade when a flat group is bound, so you shouldn’t run into this in normal use, but the picker is the only guard. If a cascade is already saved and the bound group is later changed to flat, deleted, or unbound, the calc keeps the cascade strategy and pays out zero rather than reverting to Fixed. See Why some calculation methods disappear for how the picker filters, and Cascade troubleshooting for the states that produce zero payouts after configuration.

When to use it

Picture a rep who closes a deal. Their manager earns a piece of that sale, and the manager’s director earns a smaller piece above that. The credit flows upward from the producer to the people responsible for them, which is exactly what upline cascade does. That same shape covers a tiered sales hierarchy, where the people positioned above a producer earn a share and the people above them earn a smaller share above that. It also extends to the deeper override structures common in real estate, insurance, and brokerage hierarchies, where principals are paid a percentage of what the agents beneath them produce across several layers. In every one of these cases the rule is the same: the people positioned above a producer share in what that producer brings in.

If you want the credit to flow the other direction, from the triggering collaborator down to the people they manage or lead, use downline cascade instead. If you want every member of a group to get the same flat amount regardless of position, use fixed. The strategy overview walks through the trade-offs.

Configuration

Upline cascade takes five integer args:

• pointsAtLayer1: points credited to the layer directly above the trigger.
• pointsAtLayer2: points credited two layers above the trigger.
• pointsAtLayer3: points credited three layers above the trigger.
• pointsAtLayer4: points credited four layers above the trigger.
• pointsAtLayer5: points credited five layers above the trigger.

Set any layer to 0 to stop the cascade at that point. You don’t need to fill in all five. Typical configurations use two or three layers and leave the rest at 0.

The strategy only shows up in the picker when the bound CollaboratorGroup uses a linearChain or parentChild structure. Bind a flat group and the option disappears, because there are no layers to walk. See Why some calculation methods disappear for how that filtering works.

On the program side, the bound group is read from the program config (config type program, key collaboratorGroupId) and the per-layer args are stored on the program engagement type (config type programEngagementTypeArg). On the distributor side, the same calc reads the bound group from the distributor config (config type distributor, key collaboratorGroupId) and reads the per-layer args from the distributor metric type (config type distributorMetricTypeArg). The arg keys are identical on both sides (pointsAtLayer1 through pointsAtLayer5). The only difference is where the bound group and the args live, so a metric-side cascade needs a group bound to the distributor and is configured on the distributor’s metric type.

Worked example

Picture a four-person linear chain:

• chain-one at position 1 (top of the chain)
• chain-two at position 2
• chain-three at position 3
• chain-four at position 4 (bottom of the chain)

You configure upline cascade with pointsAtLayer1: 100, pointsAtLayer2: 50, pointsAtLayer3: 25, pointsAtLayer4: 0.

chain-four makes a sale.

The cascade starts at chain-four and walks upward. Layer 1 is chain-three, one step above the trigger, and earns 100 points. Layer 2 is chain-two, two steps above, and earns 50. Layer 3 is chain-one, three steps above, and earns 25. Layer 4 is 0, so the cascade stops. chain-four earns nothing from this calculation, because the trigger never credits the collaborator that caused it.

A parent-child tree behaves the same way. Because upline follows a single line of ancestors, the trigger’s parent is layer 1, its grandparent is layer 2, and so on, so this linear-chain example covers the parent-child case too.

The shape is the same on the distributor side. If chain-four were a distributor instead of a program collaborator, the upline cascade would walk the bound distributor CollaboratorGroup and credit chain-three, chain-two, and chain-one at 100, 50, and 25, but the credits would land in metric rows on the distributor side instead of engagement rows on the program side. The walk is the same. What receives the credit is what changes.

For the conceptual background on how cascades work across program and distributor sides, see What is a cascade.