> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.royalti.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Create split
> **Create Revenue Split**
This endpoint requires authentication. Include your Bearer token in the Authorization header.
## Description
**Create Revenue Split**
The Split Revenue endpoint allows you to split revenue generated from a specific asset and product among multiple users. This endpoint calculates the revenue shares based on the provided split percentages for each user.
**Method:**
POST
**Temporal Splits & Date Ranges:**
* Splits support temporal periods with `startDate` and `endDate`
* **startDate is INCLUSIVE** - the split becomes active on this date
* **endDate is EXCLUSIVE** - the split ends before this date (not included)
* Example: `startDate: "2025-01-01", endDate: "2025-04-01"` covers Jan 1 through Mar 31
* Adjacent splits: Next split can start on the previous split's endDate (no gap)
* Permanent splits: Omit both dates for indefinite coverage
**Split Succession Pattern:**
To create a chain of temporal splits without gaps:
1. Q1 Split: `startDate: "2025-01-01", endDate: "2025-04-01"` (covers Jan-Mar)
2. Q2 Split: `startDate: "2025-04-01", endDate: "2025-07-01"` (starts Apr 1, covers Apr-Jun)
3. Q3 Split: `startDate: "2025-07-01", endDate: "2025-10-01"` (starts Jul 1, covers Jul-Sep)
**Validation:**
* Split shares must total exactly 100%
* Overlapping temporal splits are prevented (same asset/product/type)
* At least one of `asset` or `product` must be provided
**Parameters:**
| Parameter | Type | Required | Description |
| ---------- | ------ | ----------- | ---------------------------------------------------------------------------------- |
| asset | string | Conditional | The UUID of the asset related to the revenue (required if product not provided) |
| product | string | Conditional | The UUID of the product related to the revenue (required if asset not provided) |
| type | string | No | The type of revenue (e.g., Publishing, YouTube, Live) |
| startDate | string | No | The start date of the split period (INCLUSIVE - period begins on this date) |
| endDate | string | No | The end date of the split period (EXCLUSIVE - period ends before this date) |
| name | string | No | The name or description of the revenue split |
| conditions | array | No | Array of condition objects for split matching (territory, DSP, usage type filters) |
| contract | string | No | Contract details |
| ContractId | string | No | Contract ID |
| memo | string | No | Additional notes |
| split | array | Yes | An array of objects containing user shares (must total 100%) |
## Code Examples
```javascript Node.js theme={null}
const response = await fetch('https://api.royalti.io/split/', {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
"asset": "sample-asset",
"product": "sample-product",
"type": "sample-type",
"startDate": "2024-01-21",
"endDate": "2024-01-21",
"name": "sample-name",
"split": [
{
"ref": "#/components/schemas/SplitShare"
}
],
"conditions": [
{
"mode": "sample-mode",
"memo": "sample-memo",
"territories": [
{}
],
"dsps": [
{}
],
"usageTypes": [
{}
],
"customDimension": "sample-customDimension",
"customValues": [
{}
]
}
],
"contract": "sample-contract",
"ContractId": "sample-ContractId",
"memo": "sample-memo"
})
});
const data = await response.json();
console.log(data);
```
```python Python theme={null}
import requests
response = requests.post(
'https://api.royalti.io/split/',
headers={
'Authorization': f'Bearer {token}'
},
json={"asset":"sample-asset","product":"sample-product","type":"sample-type","startDate":"2024-01-21","endDate":"2024-01-21","name":"sample-name","split":[{"ref":"#/components/schemas/SplitShare"}],"conditions":[{"mode":"sample-mode","memo":"sample-memo","territories":[{}],"dsps":[{}],"usageTypes":[{}],"customDimension":"sample-customDimension","customValues":[{}]}],"contract":"sample-contract","ContractId":"sample-ContractId","memo":"sample-memo"}
)
data = response.json()
print(data)
```
```bash cURL theme={null}
curl -X POST https://api.royalti.io/split/ \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"asset":"sample-asset","product":"sample-product","type":"sample-type","startDate":"2024-01-21","endDate":"2024-01-21","name":"sample-name","split":[{"ref":"#/components/schemas/SplitShare"}],"conditions":[{"mode":"sample-mode","memo":"sample-memo","territories":[{}],"dsps":[{}],"usageTypes":[{}],"customDimension":"sample-customDimension","customValues":[{}]}],"contract":"sample-contract","ContractId":"sample-ContractId","memo":"sample-memo"}'
```
## OpenAPI
````yaml post /split/
openapi: 3.0.0
info:
title: Royalti.io API
description: "# Royalti API\r\n\r\nThis is the Royalti music royalty management platform API server.\r\n\r\n## Overview\r\n\r\nThe Royalti API provides comprehensive music royalty management services including:\r\n- Music publishing and writer management\r\n- Royalty processing and analytics\r\n- DDEX integration for music industry standards\r\n- File processing and pattern recognition\r\n- Payment processing and distribution\r\n\r\n## Authentication\r\n\r\nThe API uses JWT-based authentication with multiple protection levels:\r\n- Public endpoints for basic operations\r\n- Protected endpoints requiring valid JWT tokens\r\n- Admin endpoints for administrative functions\r\n\r\n## Features\r\n\r\n- Multi-dimensional royalty analytics\r\n- CWR (Collective Works Registration) support\r\n- DDEX integration for music metadata\r\n- Advanced file processing with pattern recognition\r\n- Real-time data processing with queue system"
version: 2.6.0
contact:
name: Royalti.io Support
email: support@royalti.io
url: https://royalti.io
license:
name: Proprietary
url: https://royalti.io/terms
servers:
- url: https://api.royalti.io
description: Production server
- url: https://api-dev.royalti.io
description: Development server
- url: http://localhost:8084
description: Local development
security:
- bearerAuth: []
tags:
- name: Accounting
description: Accounting and financial transaction operations
- name: DDEX
description: DDEX operations (ERN/MEAD, messages, delivery, providers)
- name: Label
description: Label management operations
- name: Internal Webhooks
description: Internal system webhooks for royalty processing and downloads
- name: Payment Webhooks
description: Payment processor webhook endpoints
- name: Billing Webhooks
description: Stripe billing and subscription webhooks
- name: Infrastructure Webhooks
description: Cloudflare domain and SSL webhooks
- name: Distribution Webhooks
description: Digital distribution platform webhooks (FUGA)
paths:
/split/:
post:
tags:
- Splits
summary: Create split
description: >-
**Create Revenue Split**
The Split Revenue endpoint allows you to split revenue generated from a
specific asset and product among multiple users. This endpoint
calculates the revenue shares based on the provided split percentages
for each user.
**Method:**
POST
**Temporal Splits & Date Ranges:**
- Splits support temporal periods with `startDate` and `endDate`
- **startDate is INCLUSIVE** - the split becomes active on this date
- **endDate is EXCLUSIVE** - the split ends before this date (not
included)
- Example: `startDate: "2025-01-01", endDate: "2025-04-01"` covers Jan 1
through Mar 31
- Adjacent splits: Next split can start on the previous split's endDate
(no gap)
- Permanent splits: Omit both dates for indefinite coverage
**Split Succession Pattern:**
To create a chain of temporal splits without gaps:
1. Q1 Split: `startDate: "2025-01-01", endDate: "2025-04-01"` (covers
Jan-Mar)
2. Q2 Split: `startDate: "2025-04-01", endDate: "2025-07-01"` (starts
Apr 1, covers Apr-Jun)
3. Q3 Split: `startDate: "2025-07-01", endDate: "2025-10-01"` (starts
Jul 1, covers Jul-Sep)
**Validation:**
- Split shares must total exactly 100%
- Overlapping temporal splits are prevented (same asset/product/type)
- At least one of `asset` or `product` must be provided
**Parameters:**
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| asset | string | Conditional | The UUID of the asset related to the
revenue (required if product not provided) |
| product | string | Conditional | The UUID of the product related to
the revenue (required if asset not provided) |
| type | string | No | The type of revenue (e.g., Publishing, YouTube,
Live) |
| startDate | string | No | The start date of the split period
(INCLUSIVE - period begins on this date) |
| endDate | string | No | The end date of the split period (EXCLUSIVE -
period ends before this date) |
| name | string | No | The name or description of the revenue split |
| conditions | array | No | Array of condition objects for split
matching (territory, DSP, usage type filters) |
| contract | string | No | Contract details |
| ContractId | string | No | Contract ID |
| memo | string | No | Additional notes |
| split | array | Yes | An array of objects containing user shares (must
total 100%) |
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
asset:
type: string
format: uuid
description: The UUID of the asset related to the revenue
product:
type: string
format: uuid
description: The UUID of the product related to the revenue
type:
type: string
nullable: true
description: The type of revenue (e.g., Publishing, YouTube, Live)
startDate:
type: string
format: date
nullable: true
description: The start date of the split period (inclusive)
endDate:
type: string
format: date
nullable: true
description: The end date of the split period (exclusive)
name:
type: string
nullable: true
description: The name or description of the revenue split
split:
type: array
items:
$ref: '#/components/schemas/SplitShare'
description: An array of objects containing user shares
conditions:
type: array
nullable: true
items:
type: object
properties:
mode:
type: string
enum:
- include
- exclude
default: include
memo:
type: string
nullable: true
territories:
type: array
items:
type: string
dsps:
type: array
items:
type: string
usageTypes:
type: array
items:
type: string
customDimension:
type: string
customValues:
type: array
items:
type: string
description: Conditions for split matching
contract:
type: string
nullable: true
ContractId:
type: string
format: uuid
nullable: true
memo:
type: string
nullable: true
required:
- split
example:
asset: d1c5b49e-95fa-4aed-930e-cf314c16a53d
product: b53230c5-2110-40ce-abe5-2112724ffb53
type: Publishing
startDate: '2022-01-01'
endDate: '2022-01-31'
name: Nigerian split train
split:
- user: cf960b5a-37cd-484a-b461-0b191b09bed1
share: 60
- user: 4e39b347-7db0-417d-a5bc-3d8493c9ce19
share: 40
responses:
'201':
description: Split created successfully
content:
application/json:
schema:
type: object
properties:
id:
type: string
format: uuid
AssetId:
type: string
format: uuid
ProductId:
type: string
format: uuid
type:
type: string
startDate:
type: string
format: date
nullable: true
endDate:
type: string
format: date
nullable: true
name:
type: string
contract:
type: string
nullable: true
ContractId:
type: string
nullable: true
conditions:
type: string
nullable: true
TenantId:
type: integer
example:
id: 8a8f3ee8-8855-4749-9649-897f9e0e6c6b
AssetId: 2e0d9f94-59eb-4ef8-adc6-9f3ddebf49fc
ProductId: 76293a6e-6c0a-4842-84b5-6bffbe1ea538
type: Publishing
startDate: '2022-01-01T00:00:00.000Z'
endDate: '2022-01-31T00:00:00.000Z'
name: Nigerian split train
contract: null
ContractId: null
conditions: null
TenantId: 2
'400':
description: Split condition error
content:
application/json:
schema:
type: object
properties:
msg:
type: string
example:
msg: 'operator does not exist: text = text[]'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
security:
- bearerAuth: []
components:
schemas:
SplitShare:
type: object
properties:
user:
type: string
format: uuid
description: The unique identifier of the user
share:
type: integer
minimum: 0
maximum: 100
description: The percentage share of the revenue for the user
Error:
type: object
properties:
success:
type: boolean
example: false
error:
type: object
properties:
code:
type: string
message:
type: string
details:
type: array
items:
type: string
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: >-
JWT Authorization header using the Bearer scheme. Format: "Bearer
{token}"
````