Parent-child structure

Parent-child is a collaborator group structure that arranges members into a tree. Each member optionally points at a parent, and one parent can have many children, so the group fans out instead of forming a single line.

How it works

Every member of a parent-child group carries a parentCollaboratorId in their metadata. That field is the entire structure. Members whose parentCollaboratorId is null, or points at a collaborator who isn’t in the group, are roots. A parent-child group can have more than one root, so you’re really managing a forest.

When a cascade runs from a triggering collaborator, it walks the tree in one of two directions. Upline means walking parent links toward the root. Downline means walking the children, then their children, and so on. Layer 1 is the immediate parent (upline) or the immediate children (downline). Layer 2 is the grandparent or the grandchildren. Layer 5 is the deepest you can configure. A cascade only ever walks the triggering collaborator’s own tree. It follows parent and child links out from the trigger, so it never crosses into a sibling tree in the same forest.

The shape matters most on the downline side. Layer N in a downline cascade can include many peers, every cousin at that depth from the trigger. If a manager has three direct reports and each of those reports has two reports of their own, a downline cascade from the manager hits three collaborators at layer 1 and six collaborators at layer 2. Every one of them is credited at the per-layer rate. Upline is always a single chain, because each member has at most one parent. Because each layer can be wide, a deep cascade on a large tree can credit a lot of people on a single sale, so set the per-layer points and the depth with your total payout in mind.

The admin UI shows the tree as an indented list. Drag a row vertically to change its place among its siblings. Drag horizontally during the vertical drag to change its depth: indent to nest the row under a new parent, outdent to lift it up the tree. A per-row parent dropdown is also available for keyboard and screen-reader users, so you can reparent without dragging.

Membership is dynamic. You can add a member with a parent pointer, drop the parent later (the child becomes a root), or reparent at any time. The admin UI prevents cycles. You can’t drop a parent onto one of its own descendants, because the resulting loop would make “upline” undefined. The API does not validate the full graph, so a payload that points two members at each other can store a cycle. The cascade walkers defend against cycles at runtime with a visited set, so the walk stops instead of looping forever, but you get a partial cascade. Check your parent pointers before you PUT them.

Suspended members earn nothing and are skipped, but they do not break the tree. A downline cascade still walks through a suspended parent to the people below it, and those people are credited at their own depth. Layers are not renumbered, so a suspended member at layer 2 leaves layer 2 unpaid while everyone below stays at their own layer. Deleting a collaborator is different. Siren removes a deleted collaborator from every group, so any children that pointed at them now have a parent outside the group and become roots, which detaches that branch from a cascade running through the deleted member. Reparent the children first if you want the branch to keep earning.

When to use it

Reach for parent-child whenever one person has direct authority over (or earns an override from) more than one downline collaborator. Brokerage hierarchies fit this shape, where a real estate or insurance principal oversees many agents and each of those agents oversees their own. The same branching shows up in an ordinary org chart, where a manager owns many direct reports who in turn lead teams of their own, and in a channel or partner program, where a partner manager oversees several partners who each manage their own sub-partners. What ties these together is the branching authority underneath them: anywhere one person sits above multiple collaborators and you want all of them counted under that person, you have the branching authority that parent-child is built to track.

If your structure is strictly linear, where one person sits above exactly one, who sits above exactly one, use linear chain instead. Linear chain is simpler to configure, and its drag-reorder UI is more direct than a tree. Parent-child only earns its complexity when the tree actually branches. If there is no hierarchy at all and every member is an equal peer, use flat.

Configuration

In the admin UI, create a collaborator group, set the structure to Parent-Child, and add members. Use the drag handles to nest or reorder rows, or pick a parent from the per-row dropdown. Save the group when the tree matches the relationships you want.

In the API, PUT to /collaborator-groups/{id}/members with each member carrying its parent in metadata:

{
  "members": [
    {
      "collaboratorId": 101,
      "metadata": { "parentCollaboratorId": null }
    },
    {
      "collaboratorId": 102,
      "metadata": { "parentCollaboratorId": 101 }
    },
    {
      "collaboratorId": 103,
      "metadata": { "parentCollaboratorId": 101 }
    },
    {
      "collaboratorId": 104,
      "metadata": { "parentCollaboratorId": 102 }
    }
  ]
}

That payload describes a group with one root (101), two children under it (102 and 103), and one grandchild under 102 (104). Omitting parentCollaboratorId or setting it to null marks a root. Pointing it at a collaborator id outside the group also marks a root. The missing parent is treated as “not in this tree.”

This PUT replaces the group’s full member list. Any member you leave out of the body is removed from the group, which also turns that member’s children into roots, so send the whole tree each time. To change one member without resending everything, use the add and remove member endpoints instead.

Once the group is saved, bind it to a program or distributor and pick a cascade calculation. Upline cascade walks toward the roots from whoever triggered the engagement. Downline cascade walks toward the leaves. The per-layer points you configure on the calc decide how much each layer earns, and 0 on any layer stops the cascade there.