Royalties

What the authenticated user is owed, and what has been paid to them

Resource Overview

Two read-only endpoints that return the royalty position of the user who owns the access token: the current available amount with its period-by-period history, and the payment history. They are the same figures the limbo dashboard shows that person.

Endpoints
/royalties/summary
/royalties/payments
Access Level
Read-only, any user with API access
Parameters
filter[period-from], filter[period-to] (optional)

Period Filter

Both endpoints accept the same optional range. Both bounds are inclusive and either may be sent alone.

Parameter Format Description
filter[period-from] YYYY-MM First month to include (e.g. 2026-01)
filter[period-to] YYYY-MM Last month to include (e.g. 2026-06)
  • • The month is two digits, 01 to 12: 2026-3 and 2026-13 are rejected, they are not corrected.
  • • /royalties/summary: the filter narrows data.evolution and meta.periods counts the filtered entries. data.current_available and meta.payees do not change.
  • • /royalties/payments: the filter narrows the list and meta.total counts the filtered list.
  • • A malformed value, or a period-from later than period-to, answers 422. It is never ignored.
GET /royalties/payments?filter[period-from]=2026-01&filter[period-to]=2026-06
GET /royalties/summary?filter[period-from]=2026-04
GET /royalties/summary?filter[period-to]=2026-02

Get Royalty Summary

GET /royalties/summary Read Only 
GET /royalties/summary
Authorization: Bearer {token}
Accept: application/vnd.api+json

Returns the current position plus the history, one entry per published period, oldest first. Accepts the optional period filter, which narrows data.evolution only: data.current_available is always the latest published period, whatever the filter.

Response Fields

Field Type Description
data.current_available string Available amount of the latest period. It is not a running total: each period already carries where the payee stands.
data.evolution array One entry per published period, oldest first. Empty when there is nothing to show.
evolution[].period_year integer Year of the period
evolution[].period_month integer Month of the period (1-12)
evolution[].closing_balance string Closing balance of the period
evolution[].total_paid string Total paid in the period
evolution[].available string Amount available at the end of the period
meta.payees integer Number of payees resolved for the authenticated user
meta.periods integer Number of entries in evolution

When the user is linked to several payees (for example, listed under their own name and under their label's), the amounts of the payees are summed within each period.

Success Response

200 OK 
{
  "data": {
    "current_available": "450.5000",
    "evolution": [
      {
        "period_year": 2026,
        "period_month": 3,
        "closing_balance": "500.0000",
        "total_paid": "200.0000",
        "available": "300.0000"
      },
      {
        "period_year": 2026,
        "period_month": 4,
        "closing_balance": "750.5000",
        "total_paid": "300.0000",
        "available": "450.5000"
      }
    ]
  },
  "meta": {
    "payees": 1,
    "periods": 2
  }
}

current_available matches the available of the latest period (April 2026), not the sum of the periods.

No Royalties Yet

A user with no matched payee, or whose statements are not published yet, receives a zeroed position. This is a normal answer, not an error.

200 OK 
{
  "data": {
    "current_available": "0.0000",
    "evolution": []
  },
  "meta": {
    "payees": 0,
    "periods": 0
  }
}

Get Royalty Payments

GET /royalties/payments Read Only 
GET /royalties/payments
Authorization: Bearer {token}
Accept: application/vnd.api+json

Returns the payments made to the authenticated user, oldest period first. Accepts the optional period filter; it is not paginated.

Response Fields

Field Type Description
data[].period_year integer Year of the period the payment belongs to
data[].period_month integer Month of the period (1-12)
data[].paid_amount string | null Amount paid, as a decimal string with four decimals. null when no amount is recorded.
data[].paid_full boolean Whether the period was paid in full
meta.total integer Number of payments returned

Success Response

200 OK 
{
  "data": [
    {
      "period_year": 2026,
      "period_month": 3,
      "paid_amount": "200.0000",
      "paid_full": true
    },
    {
      "period_year": 2026,
      "period_month": 4,
      "paid_amount": null,
      "paid_full": false
    }
  ],
  "meta": {
    "total": 2
  }
}

A user with no matched payee, or with no published payments, receives "data": [] and "meta": {"total": 0} with 200 OK.

Errors

Status Code When
401 - The request carries no valid bearer token
403 royalties-disabled The royalties statement feature is not enabled in this environment
422 - A period filter is malformed (not YYYY-MM, month outside 01-12) or filter[period-from] is later than filter[period-to]

The endpoints can be switched off per environment. When they are, both answer:

403 Forbidden 
{
  "errors": [
    {
      "status": "403",
      "code": "royalties-disabled",
      "title": "Forbidden",
      "detail": "The royalties statement feature is not enabled."
    }
  ]
}

An invalid period filter answers, naming the offending parameter in source.parameter (here for filter[period-from]=2026-13):

422 Unprocessable Entity 
{
  "jsonapi": { "version": "1.0" },
  "errors": [
    {
      "detail": "The filter[period-from] must be a month in YYYY-MM format.",
      "source": { "parameter": "filter.period-from" },
      "status": "422",
      "title": "Unprocessable Entity"
    }
  ]
}

Usage Examples

Show the Current Balance

Read the amount available for the latest published period

GET /royalties/summary

# data.current_available -> "450.5000"

Chart the Evolution

Use data.evolution, already ordered from the oldest period to the latest

GET /royalties/summary

# data.evolution[].period_year / period_month -> x axis
# data.evolution[].available                   -> y axis

List the Payment History

Show each payment and whether the period was settled in full

GET /royalties/payments

# data[].paid_full -> false: the period was not paid in full