Operating a cascade program

Setting up a cascade is a one-time job. Running it is ongoing. People join the team, leave the team, and move up or down the chain. This page covers the day-to-day work of keeping a live cascade group accurate, and what happens to an in-flight cascade when its membership changes.

If you haven’t built a cascade yet, start with Create a collaborator group and Configure cascade payouts. This page assumes a group already exists and is bound to a program or distributor.

Editing membership from the admin UI

Open the group from the Collaborator Groups list under the Siren menu. The edit screen shows the members table. Every membership change happens here, and nothing is persisted until you click Save.

Add members

Click Add Members to open the collaborator picker modal. Search by name or email, check the collaborators you want, and stage them. Staged rows appear in the members table with a pending indicator. Click Save to commit them.

Adding a member who is already in the group is a no-op. The add path skips any collaborator that already has a membership row, so you can re-run an add without creating duplicates.

Remove members

Each row has a remove control. Removing a row stages the removal. As with adds, nothing leaves the group until you Save.

Reorder members

Reordering only applies to linear chain and parent-child groups. Flat groups have no order, so there is nothing to arrange.

In a linear chain group, drag a row by its handle to move it up or down. Position 1 sits at the top and is the most upline. Siren recomputes the position values on save based on the visual order, so you never type a number. In a parent-child group, drag to reparent or use the Parent dropdown to pick a parent directly. Siren prevents cycles, so you can’t make a collaborator its own descendant’s parent.

Because reordering changes per-member metadata (the position for a chain, the parentCollaboratorId for a tree), reordering a live group changes how the cascade walks it. See How membership changes hit an in-flight cascade below.

The membership endpoints

The admin UI drives three REST endpoints under the group’s /members path. You’ll see these if you script membership changes or read the network traffic while editing a group. All three require the Update capability on CollaboratorGroup, which only an administrator or Platform Manager holds.

Endpoint	Method	What it does
AddCollaboratorGroupMembers	POST /collaborator-groups/{id}/members	Bulk-adds members. Collaborators that already have a row are skipped. Returns the newly-added rows.
RemoveCollaboratorGroupMember	DELETE /collaborator-groups/{id}/members/{collaboratorId}	Removes a single collaborator. Returns 204 on success, 404 when the membership row does not exist.
SetCollaboratorGroupMembers	PUT /collaborator-groups/{id}/members	Full-replace of the member set. Reconciles the submitted list against what’s there: adds new collaborators, removes ones no longer listed, and updates metadata on the rest.

AddCollaboratorGroupMembers and SetCollaboratorGroupMembers take a members array of { "collaboratorId": int, "metadata": object } entries, where metadata is where chain position or tree parentCollaboratorId lives. SetCollaboratorGroupMembers is the one the UI uses for a full save, because it reconciles the whole roster in a single call instead of issuing separate add and remove requests.

What CollaboratorGroupMemberMetadataChanged means

SetCollaboratorGroupMembers reconciles the roster member by member. For each collaborator it does one of three things, and each path broadcasts a different event:

• A collaborator in the submitted list who has no current row is created, which broadcasts CollaboratorAddedToCollaboratorGroup.
• A collaborator with a current row whose submitted metadata differs from the stored metadata is updated, which broadcasts CollaboratorGroupMemberMetadataChanged.
• A collaborator with a current row who is absent from the submitted list is deleted, which broadcasts CollaboratorRemovedFromCollaboratorGroup.

CollaboratorGroupMemberMetadataChanged (event id collaborator_group_member_metadata_changed) fires only when an existing member’s metadata actually changes. It carries the groupId, the collaboratorId, the previousMetadata, and the newMetadata. If the submitted metadata matches what’s already stored, no update runs and no event fires. This is the event that tells you a member was reordered or reparented rather than added or removed. In practice that means a chain member’s position changed, or a tree member’s parent changed, while the member stayed in the group.

How membership changes hit an in-flight cascade

A cascade is computed at trigger time, not stored as a fixed payout plan. It walks the bound group’s current structure each time an engagement or metric fires. So membership changes take effect on the next trigger, not retroactively.

Credits already produced by past triggers are independent. They are recorded as engagements and obligations that don’t recompute when you change the group. Editing the roster shapes future cascades, not ones that already fired.

Three changes are worth thinking through before you make them on a live group.

Reordering changes who earns which layer

Layer numbers are derived from the walker’s position in the chain or tree, not from a stored value on the member. When you reorder a chain or reparent a tree node, the next trigger walks the new shape. A collaborator you moved up the chain starts earning a nearer (higher-value) layer, and the one you moved down earns a further one. Nothing about past credits changes. The new order governs the next walk.

Removing a member shortens the walk for everyone below them

Removing a member from a chain or tree closes the gap. The members that were below the removed one each move up by a layer on the next trigger, because the walk no longer steps through the missing member. If you remove someone mid-chain, the layer they used to occupy is gone, and the cascade continues straight through to the next member.

Suspending versus deleting a chain member

There are two distinct cases, and they behave differently from each other and from a removal.

A collaborator who is still a group member but is not active (suspended, pending, or otherwise not active) is skipped by the cascade with no credit, and their layer simply goes unpaid for that trigger. The cascade keeps walking, but it does not renumber and does not move anyone else into the empty layer. Every other member keeps their own layer and per-layer rate, so the person below a suspended member does not move up and does not collect the suspended layer’s credit. In a parent-child tree, where a layer can hold several peers, the other active peers at that layer still earn, because the skip only drops the one inactive peer. The inactive member keeps their slot and starts earning in the same position the moment they’re set back to Active, with no roster edit required. The same skip behavior is documented for Upline cascade and Downline cascade.

Deleting a collaborator outright is different. When a collaborator is deleted, Siren automatically removes them from every group they belonged to. The CleanupCollaboratorGroupMembershipsOnCollaboratorDelete listener responds to the collaborator-deleted event and deletes all of that collaborator’s membership rows. It removes membership rows only. It does not delete the groups themselves. After a delete, the deleted collaborator is no longer a member of any group, so subsequent cascades walk the group as if that member never existed, with everyone below them shifting up a layer.

The practical difference: suspend a chain member when they’re temporarily out and you want them to slot back into the same position later. Delete (or remove) them when the change is permanent and you want the chain to close the gap.

What you’ve done

You now know how to keep a live cascade group accurate from the admin UI, which endpoints the UI drives behind the scenes, what CollaboratorGroupMemberMetadataChanged signals, and how adds, removals, reorders, suspensions, and deletes each play out on the next cascade trigger.

A few places to go next:

• Configure cascade payouts: the setup tutorial, if you need to revisit per-layer config.
• Upline cascade and Downline cascade: the per-strategy reference for skip and stop behavior.
• Managing collaborators: how status changes (Active, Pending, Inactive) and deletes work on the collaborator side.