Payout Rules

A payout rule encapsulates the logic that is used to divide a bill's calculated fee among payout recipients. Use the payout rule API to manage the set of rules that are available for assignment to billable portfolios.

Billing payouts is in closed beta

The ability to use and manage the payout features described herein is available only to a pre-selected group of Addepar clients within the Addepar Beta Program.


Base route	`/v1/billing/payout/rules`
Endpoints	GET `/v1/billing/payout/rules` `/v1/billing/payout/rules/:id` POST `/v1/billing/payout/rules` PUT `/v1/billing/payout/rules/:id` DELETE `/v1/billing/payout/rules/:id`
Produces	JSON
Pagination	Yes
Application permissions required	"Run and manage bills, include fee adjustment and payment tracking" or "Full access to Billing and billing data"
OAuth scopes	`BILLING_WRITE`

Access requirements

To use this endpoint, your API key must have one of the following application permissions:

"Run and manage bills, include fee adjustment and payment tracking"

"Full access to Billing and billing data"

Your OAuth token must include the BILLING_WRITE scope.

Payout rule structure

A payout rule is comprised of some metadata (a name and description) and a hierarchy of splits that define how much of a bill's total fee is given to a recipient. Splits are subject to validation rules:

The percentage-based splits at a given level of division must sum to 100%. This implies that there is at least one percentage-based split in the level.
Fixed-amount splits can only exist at the top level of division, and cannot be subdivided
Percentage-based splits can have only a single level of subdivision

For example:

The simplest possible split structure is a single percentage-based split that gives 100% of the billed value to the recipient
A straightforward division between two recipients would have 2 top-level splits
A fixed split gives the recipient the same amount from every bill, regardless of the bill's calculated fee.
A top-level split to a team can be subdivided to the team's members

{
  "data": {
    "type": "payout_rule",
    "id": "1",
    "attributes": {
      "name": "Simple",
      "description": "Everything to one recipient",
      "splits": [
        {
          "recipient": {
            "type": "payout_recipient",
            "id": "10",
            "attributes": {
              "name": "John Jackson",
              "type": "Senior advisor"
            }
          },
          "distribution_type": "PERCENTAGE",
          "distribution_amount": 100.0,
          "children": []
        }
      ]
    }
  }
}

{
  "data": {
    "type": "payout_rule",
    "id": "2",
    "attributes": {
      "name": "Two-way",
      "description": "70/30 to advisors",
      "splits": [
        {
          "recipient": {
            "type": "payout_recipient",
            "id": "10",
            "attributes": {
              "name": "John Jackson",
              "type": "Senior advisor"
            }
          },
          "distribution_type": "PERCENTAGE",
          "distribution_amount": 70.0,
          "children": []
        },
        {
          "recipient": {
            "type": "payout_recipient",
            "id": "12",
            "attributes": {
              "name": "Jack Johnson",
              "type": "Junior advisor"
            }
          },
          "distribution_type": "PERCENTAGE",
          "distribution_amount": 30.0,
          "children": []
        }
      ]
    }
  }
}

{
  "data": {
    "type": "payout_rule",
    "id": "3",
    "attributes": {
      "name": "Referral",
      "description": "$500 sales incentive",
      "splits": [
        {
          "recipient": {
            "type": "payout_recipient",
            "id": "10",
            "attributes": {
              "name": "Pete Campbell",
              "type": "Account executive"
            }
          },
          "distribution_type": "FIXED",
          "distribution_amount": 500.0,
          "children": []
        },
        {
          "recipient": {
            "type": "payout_recipient",
            "id": "12",
            "attributes": {
              "name": "Jack Johnson",
              "type": "Junior advisor"
            }
          },
          "distribution_type": "PERCENTAGE",
          "distribution_amount": 100.0,
          "children": []
        }
      ]
    }
  }
}

{
  "data": {
    "type": "payout_rule",
    "id": "4",
    "attributes": {
      "name": "Subdivision",
      "description": "20/50/30 to firm, advisors and analysts",
      "splits": [
        {
          "recipient": {
            "type": "payout_recipient",
            "id": "16",
            "attributes": {
              "name": "ABC wealth management",
              "type": "Firm"
            }
          },
          "distribution_type": "PERCENTAGE",
          "distribution_tmount": 20.0,
          "children": []
        },
        {
          "recipient": {
            "type": "payout_recipient",
            "id": "17",
            "attributes": {
              "name": "Advisor",
              "type": "Team"
            }
          },
          "distribution_type": "PERCENTAGE",
          "distribution_amount": 50.0,
          "children": [
            {
              "recipient": {
                "type": "payout_recipient",
                "id": "12",
                "attributes": {
                  "name": "John Jackson",
                  "type": "Senior advisor"
                }
              },
              "distribution_type": "PERCENTAGE",
              "distribution_amount": 70.0,
              "children": []
            },
            {
              "recipient": {
                "type": "payout_recipient",
                "id": "13",
                "attributes": {
                  "name": "Jack Johnson",
                  "type": "Junior advisor"
                }
              },
              "distribution_type": "PERCENTAGE",
              "distribution_amount": 30.0,
              "children": []
            }
          ]
        },
        {
          "recipient": {
            "type": "payout_recipient",
            "id": "17",
            "attributes": {
              "name": "Analysis",
              "type": "Team"
            }
          },
          "distribution_type": "PERCENTAGE",
          "distribution_amount": 30.0,
          "children": [
            {
              "recipient": {
                "type": "payout_recipient",
                "id": "18",
                "attributes": {
                  "name": "Grace Hopper",
                  "type": "Senior analyst"
                }
              },
              "distribution_type": "PERCENTAGE",
              "distribution_amount": 80.0,
              "children": []
            },
            {
              "recipient": {
                "type": "payout_recipient",
                "id": "19",
                "attributes": {
                  "name": "Ron Paxton",
                  "type": "Junior analyst"
                }
              },
              "distribution_type": "PERCENTAGE",
              "distribution_amount": 20.0,
              "children": []
            }
          ]
        }
      ]
    }
  }
}

Resource attributes

Arguments are described by the below resource object attributes and will appear in successful POST and PUT responses.

Attribute	Description
`id`	The payout rule's ID. Integer type. Example: `1234`

Parameters

Attribute	Description
`name`	The primary identifier for the recipient. Example: `Standard split`
`description`	An optional descriptive string for the rule. Example: `10/70/20 Firm/advisor/admin`
`splits`	A list of the base-level value allocations
`splits[].recipient`	The recipient of the allocation
`splits[].distribution_type`	Whether the allocation is of a fixed value or a portion of billed value. Example: `FIXED`, `PERCENTAGE`
`splits[].distribution_amount`	The allocated amount (for `FIXED` type), or the amount percentage (for `PERCENTAGE` type). Example: `80`
`splits[].children`	The subdivision splits

Get rules

Get a paginated list of rules (in name order) with:

GET /v1/billing/payout/rules

Authentication

This endpoint requires a valid API key. Include your credentials in the header:
Authorization: Basic base64(key_id:key_secret)

The request supports filtering by rule name and recipient, and result pagination via query parameters:

search -- Only rules whose names match (case insensitive) the search term will be returned
recipient_ids -- Only those rules that include all of the identified recipients will be returned. Multiple recipient IDs can be included in the filter by repeating the query parameter
offset -- How many rules in the search result set to skip
limit -- The maximum number of rules to return

Example

curl -X GET "https://{firm}.addepar.com/api/v1/billing/payout/rules" \
  -H "Authorization: Basic {credentials}" \
  -H "Accept: application/json"

{
  "data": [
    {
      "data": {
        "type": "payout_rule",
        "id": "1",
        "attributes": {
          "name": "Jack",
          "description": "Everything to Jack",
          "splits": [
            {
              "recipient": {
                "type": "payout_recipient",
                "id": "10",
                "attributes": {
                  "name": "Jack Johnson",
                  "type": "Senior advisor"
                }
              },
              "distribution_type": "PERCENTAGE",
              "distribution_amount": 100.0,
              "children": []
            }
          ]
        }
      }
    },
    {
      "data": {
        "type": "payout_rule",
        "id": "2",
        "attributes": {
          "name": "John",
          "description": "Everything to John",
          "splits": [
            {
              "recipient": {
                "type": "payout_recipient",
                "id": "11",
                "attributes": {
                  "name": "John Jackson",
                  "type": "Junior advisor"
                }
              },
              "distribution_type": "PERCENTAGE",
              "distribution_amount": 100.0,
              "children": []
            }
          ]
        }
      }
    }
  ],
  "meta": {
    "page": {
      "total": 2,
      "cursor": 0,
      "limit": 500
    }
  }
}

Example with search filter

curl -X GET "https://{firm}.addepar.com/api/v1/billing/payout/rules?search=john" \
  -H "Authorization: Basic {credentials}" \
  -H "Accept: application/json"

{
  "data": [
    {
      "data": {
        "type": "payout_rule",
        "id": "2",
        "attributes": {
          "name": "John",
          "description": "Everything to John",
          "splits": [
            {
              "recipient": {
                "type": "payout_recipient",
                "id": "11",
                "attributes": {
                  "name": "John Jackson",
                  "type": "Junior advisor"
                }
              },
              "distribution_type": "PERCENTAGE",
              "distribution_amount": 100.0,
              "children": []
            }
          ]
        }
      }
    }
  ],
  "meta": {
    "page": {
      "total": 1,
      "cursor": 0,
      "limit": 500
    }
  }
}

Example with recipient filter

curl -X GET "https://{firm}.addepar.com/api/v1/billing/payout/rules?recipient_ids=10" \
  -H "Authorization: Basic {credentials}" \
  -H "Accept: application/json"

{
  "data": [
    {
      "data": {
        "type": "payout_rule",
        "id": "1",
        "attributes": {
          "name": "Jack",
          "description": "Everything to Jack",
          "splits": [
            {
              "recipient": {
                "type": "payout_recipient",
                "id": "10",
                "attributes": {
                  "name": "Jack Johnson",
                  "type": "Senior advisor"
                }
              },
              "distribution_type": "PERCENTAGE",
              "distribution_amount": 100.0,
              "children": []
            }
          ]
        }
      }
    }
  ],
  "meta": {
    "page": {
      "total": 1,
      "cursor": 0,
      "limit": 500
    }
  }
}

Response codes:

200 OK -- Success
403 Forbidden -- Insufficient application permissions or appropriate scope not granted

Get rule

Single rules can be retrieved by ID.

GET /v1/billing/payout/rules/:id

Example

curl -X GET "https://{firm}.addepar.com/api/v1/billing/payout/rules/1" \
  -H "Authorization: Basic {credentials}" \
  -H "Accept: application/json"

{
  "data": {
    "type": "payout_rule",
    "id": "1",
    "attributes": {
      "name": "Simple",
      "description": "Everything to one recipient",
      "splits": [
        {
          "recipient": {
            "type": "payout_recipient",
            "id": "10",
            "attributes": {
              "name": "John Jackson",
              "type": "Senior advisor"
            }
          },
          "distribution_type": "PERCENTAGE",
          "distribution_amount": 100.0,
          "children": []
        }
      ]
    }
  }
}

Response codes:

200 OK -- Success
403 Forbidden -- Insufficient application permissions or appropriate scope not granted
404 Not Found -- Rule does not exist

Create rules

Rules can be created individually or in bulk.

When specifying the recipient of a split, only supply the recipient's ID value.

POST /v1/billing/payout/rules

Example

curl -X POST "https://{firm}.addepar.com/api/v1/billing/payout/rules" \
  -H "Authorization: Basic {credentials}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
  "data": {
    "type": "payout_rule",
    "id": "1",
    "attributes": {
      "name": "Jack",
      "description": "Everything to Jack",
      "splits": [
        {
          "recipient": {
            "id": "10"
          },
          "distribution_type": "PERCENTAGE",
          "distribution_amount": 100.0,
          "children": []
        }
      ]
    }
  }
}'

{
  "data": {
    "type": "payout_rule",
    "id": "1",
    "attributes": {
      "name": "Jack",
      "description": "Everything to Jack",
      "splits": [
        {
          "recipient": {
            "type": "payout_recipient",
            "id": "10",
            "attributes": {
              "name": "Jack Johnson",
              "type": "Senior advisor"
            }
          },
          "distribution_type": "PERCENTAGE",
          "distribution_amount": 100.0,
          "children": []
        }
      ]
    }
  }
}

Example (bulk create)

curl -X POST "https://{firm}.addepar.com/api/v1/billing/payout/rules" \
  -H "Authorization: Basic {credentials}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
  "data": [
    {
      "data": {
        "type": "payout_rule",
        "id": "1",
        "attributes": {
          "name": "Jack",
          "description": "Everything to Jack",
          "splits": [
            {
              "recipient": {
                "id": "10"
              },
              "distribution_type": "PERCENTAGE",
              "distribution_amount": 100.0,
              "children": []
            }
          ]
        }
      }
    },
    {
      "data": {
        "type": "payout_rule",
        "id": "2",
        "attributes": {
          "name": "John",
          "description": "Everything to John",
          "splits": [
            {
              "recipient": {
                "id": "11"
              },
              "distribution_type": "PERCENTAGE",
              "distribution_amount": 100.0,
              "children": []
            }
          ]
        }
      }
    }
  ]
}'

{
  "data": [
    {
      "data": {
        "type": "payout_rule",
        "id": "1",
        "attributes": {
          "name": "Jack",
          "description": "Everything to Jack",
          "splits": [
            {
              "recipient": {
                "type": "payout_recipient",
                "id": "10",
                "attributes": {
                  "name": "Jack Johnson",
                  "type": "Senior advisor"
                }
              },
              "distribution_type": "PERCENTAGE",
              "distribution_amount": 100.0,
              "children": []
            }
          ]
        }
      }
    },
    {
      "data": {
        "type": "payout_rule",
        "id": "2",
        "attributes": {
          "name": "John",
          "description": "Everything to John",
          "splits": [
            {
              "recipient": {
                "type": "payout_recipient",
                "id": "11",
                "attributes": {
                  "name": "John Jackson",
                  "type": "Junior advisor"
                }
              },
              "distribution_type": "PERCENTAGE",
              "distribution_amount": 100.0,
              "children": []
            }
          ]
        }
      }
    }
  ]
}

Response codes:

201 Created -- Success
400 Bad request -- Failed during validation (e.g., missing required name attribute or invalid split structure).
403 Forbidden -- Insufficient application permissions or appropriate scope not granted

Update rules

Existing rules can be updated via their ID:

PUT /v1/billing/payout/rules/:id

Example

curl -X PUT "https://{firm}.addepar.com/api/v1/billing/payout/rules/1" \
  -H "Authorization: Basic {credentials}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
  "data": {
    "type": "payout_rule",
    "id": "1",
    "attributes": {
      "name": "John (promotion)",
      "description": "John has taken over Jack'\''s accounts",
      "splits": [
        {
          "recipient": {
            "id": "11"
          },
          "distribution_type": "PERCENTAGE",
          "distribution_amount": 100.0,
          "children": []
        }
      ]
    }
  }
}'

{
  "data": {
    "type": "payout_rule",
    "id": "1",
    "attributes": {
      "name": "John (promotion)",
      "description": "John has taken over Jack's accounts",
      "splits": [
        {
          "recipient": {
            "type": "payout_recipient",
            "id": "11",
            "attributes": {
              "name": "John Jackson",
              "type": "Senior advisor"
            }
          },
          "distribution_type": "PERCENTAGE",
          "distribution_amount": 100.0,
          "children": []
        }
      ]
    }
  }
}

Response codes:

200 OK -- Success
400 Bad request -- Failed during validation (e.g., missing required name attribute or invalid split structure).
403 Forbidden -- Insufficient application permissions or appropriate scope not granted
404 Not Found -- Rule does not exist

Delete rules

Existing rules can be deleted individually or in bulk via their ID. Rules may not be deleted if they are currently assigned to a billable portfolio.

DELETE /v1/billing/payout/rules/:id

DELETE /v1/billing/payout/rules

Example

curl -X DELETE "https://{firm}.addepar.com/api/v1/billing/payout/rules/1" \
  -H "Authorization: Basic {credentials}" \
  -H "Accept: application/json"

Example (bulk delete)

curl -X DELETE "https://{firm}.addepar.com/api/v1/billing/payout/rules" \
  -H "Authorization: Basic {credentials}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
  "data": [
    {
      "type": "payout_rule",
      "id": 1
    },
    {
      "type": "payout_rule",
      "id": 2
    }
  ]
}'

Response codes:

204 No content -- Success
400 Bad Request -- Failed during validation (e.g.: if the rule is still assigned to a portfolio)
403 Forbidden -- Insufficient application permissions or appropriate scope not granted
404 Not Found -- Rule does not exist
409 Conflict -- If the request body type is not payout_rule.

Related resources

Payout Recipients | Billing | Fee Schedules