Enable, disable, or configure a capability

curl --request PUT \
  --url https://api.royalti.io/capabilities/{slug} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "enabled": true
}
'

{
  "status": "success",
  "message": "Capability updated",
  "data": {
    "slug": "paystack",
    "kind": "connection",
    "name": "VertoFX",
    "description": "Send cross-border payouts and manage beneficiaries through VertoFX.",
    "enabled": true,
    "settings": {},
    "settingsVersion": 1,
    "settingsSchema": {},
    "hasCredentials": true,
    "credentialShape": [
      "apiKey",
      "clientId"
    ],
    "requiresConfig": true,
    "connectionStatus": {
      "connected": true,
      "message": "<string>",
      "availablePeriods": [
        "202401",
        "202402",
        "202403"
      ],
      "dspFolders": [
        "DistroKid",
        "CD Baby",
        "TuneCore"
      ]
    },
    "lastConnectionTest": "2023-11-07T05:31:56Z",
    "connectionError": "<string>",
    "features": {
      "royaltyImport": true,
      "invoiceImport": false
    }
  }
}

PUT

capabilities

{slug}

curl --request PUT \
  --url https://api.royalti.io/capabilities/{slug} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "enabled": true
}
'

{
  "status": "success",
  "message": "Capability updated",
  "data": {
    "slug": "paystack",
    "kind": "connection",
    "name": "VertoFX",
    "description": "Send cross-border payouts and manage beneficiaries through VertoFX.",
    "enabled": true,
    "settings": {},
    "settingsVersion": 1,
    "settingsSchema": {},
    "hasCredentials": true,
    "credentialShape": [
      "apiKey",
      "clientId"
    ],
    "requiresConfig": true,
    "connectionStatus": {
      "connected": true,
      "message": "<string>",
      "availablePeriods": [
        "202401",
        "202402",
        "202403"
      ],
      "dspFolders": [
        "DistroKid",
        "CD Baby",
        "TuneCore"
      ]
    },
    "lastConnectionTest": "2023-11-07T05:31:56Z",
    "connectionError": "<string>",
    "features": {
      "royaltyImport": true,
      "invoiceImport": false
    }
  }
}

This endpoint requires authentication. Include your Bearer token in the Authorization header.

Description

other key is accepted (400 UNKNOWN_FIELDS; credentials go to PUT /capabilities/{slug}/credentials). When settings is given it is deep-merged into the stored value (nested objects recurse, arrays replace whole, null deletes a key) and validated against the capability’s settingsSchema before enabled is applied, in one transaction — an invalid patch changes nothing. A publisher settings update also best-effort syncs the tenant’s own Publisher record; a merlin onEnable/onDisable hook provisions/tears down its scheduled import. Authorization:

Required role: admin or higher
Changing enabled on a connection capability (paystack, vertofx, merlin) requires owner; settings-only updates on a connection stay admin

Code Examples

const response = await fetch('https://api.royalti.io/capabilities/{slug}', {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "enabled": true,
    "settings": {}
  })
});

const data = await response.json();
console.log(data);

import requests

response = requests.put(
  'https://api.royalti.io/capabilities/{slug}',
  headers={
    'Authorization': f'Bearer {token}'
  },
  json={"enabled":true,"settings":{}}
)

data = response.json()
print(data)

curl -X PUT https://api.royalti.io/capabilities/{slug} \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true,"settings":{}}'

Authorizations

Authorization

string

header

required

JWT Authorization header using the Bearer scheme. Format: "Bearer {token}"

Path Parameters

slug

enum<string>

required

Stable identifier; never renamed after ship.

Available options:

paystack,

vertofx,

merlin,

ddex-delivery,

publisher,

distro,

release,

payment-requests,

email-branding,

catalog-media

Body

application/json

enabled

boolean

settings

object

Deep-merged patch, validated against the capability's settingsSchema.

Response

Capability updated

status

string

Example:

"success"

message

string

Example:

"Capability updated"

data

object

One entry in GET /capabilities data, and the shape of every write response's data.

Show child attributes

​Description

​Code Examples

Authorizations

Path Parameters

Body

Response

Description

Code Examples