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. All beta features described herein are provided “as is'” and “as available” with no warranty or guarantee of functionality and may be modified or removed at any time by Addepar.
| Base route | /v1/billing/payout/rules |
| Endpoints | GET/v1/billing/payout/rules/v1/billing/payout/rules/:idPOST /v1/billing/payout/rulesPUT /v1/billing/payout/rules/:idDELETE /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 |
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 overview
Arguments are described by the below resource object attributes and will appear in successful POST and PUT responses.
| Attribute | Description | Example |
|---|---|---|
id | The payout rule's ID. Integer type | 1234 |
Parameters
| Parameter | Description | Example |
|---|---|---|
name | The primary identifier for the recipient | Standard split |
description | An optional descriptive string for the rule | 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 | FIXEDPERCENTAGE |
splits[].distribution_amount | The allocated amount (for FIXED type), or the amount percentage (for PERCENTAGE type). | 80 |
splits[].children | The subdivision splits |
Get rules
Get a paginated list of rules (in name order) with:
GET /v1/billing/payout/rules
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 returnedrecipient_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 parameteroffset- How many rules in the search result set to skiplimit- The maximum number of rules to return
Example
GET https://examplefirm.addepar.com/api/v1/billing/payout/rules
HTTP/1.1 200
{
"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
GET https://examplefirm.addepar.com/api/v1/billing/payout/rules?search=john
HTTP/1.1 200
{
"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
GET https://examplefirm.addepar.com/api/v1/billing/payout/rules?recipient_ids=10
HTTP/1.1 200
{
"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: Success403 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
GET https://examplefirm.addepar.com/api/v1/billing/payout/rules/1
HTTP/1.1 200
{
"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: Success403 Forbidden: Insufficient application permissions or appropriate scope not granted404 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
POST https://examplefirm.addepar.com/api/v1/billing/payout/rules
{
"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": []
}
]
}
}
}
HTTP/1.1 201
{
"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
POST https://examplefirm.addepar.com/api/v1/billing/payout/rules
{
"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": []
}
]
}
}
}
]
}
HTTP/1.1 201
{
"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: Success400 Bad request: Failed during validation (e.g., missing requirednameattribute 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
PUT https://examplefirm.addepar.com/api/v1/billing/payout/rules/1
{
"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": []
}
]
}
}
}
HTTP/1.1 200
{
"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: Success400 Bad request: Failed during validation (e.g., missing requirednameattribute or invalid split structure).403 Forbidden: Insufficient application permissions or appropriate scope not granted404 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
DELETE https://examplefirm.addepar.com/api/v1/billing/payout/rules/1
HTTP/1.1 204
Example
DELETE https://examplefirm.addepar.com/api/v1/billing/payout/rules
{
"data": [
{
"type": "payout_rule",
"id": 1
},
{
"type": "payout_rule",
"id": 2
}
]
}
HTTP/1.1 204
Response codes:
204 No content: Success400 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 granted404 Not Found: Rule does not exist409 Conflict: If the request bodytypeis notpayout_rule.
Updated 17 days ago
Did this page help you?