Sub-labels and white label

A master label, or a white label running sub-labels under its own brand, can drive every sub-label from one system with one key. Each sub-label stays its own account, with its own releases, statements and agreement; the key moves between them with one header.

1. Make the sub-labels#

Sub-labels are made in the workspace: Workspace › Label network › New sub-label. Each one is a separate account below yours. Its releases, review, money and limits are its own, and the label network shows what each has done.

A white label also sets what its sub-labels and their artists see in Workspace › White label: the brand, the sign-in page at your own address, the emails and the help centre.

2. Let the key act for them#

An owner or admin turns on Sub-labels on the key in Workspace › API, with a code from their authenticator app. GET /organizations then lists every organization the key can act for: its own, and the sub-labels below it that the key's member can open.

import { StillmoreApi } from "./stillmore-api";

const api = new StillmoreApi({ apiKey: process.env.STILLMORE_API_KEY! });
const organizations = await api.get<Array<{ id: string; name: string }>>("/organizations");

3. Name the sub-label on each call#

Send the sub-label's id in the Stillmore-Organization header. Every id, list and limit is then that sub-label's, as if it had its own key: a release created this way is the sub-label's release, and GET /balance is the sub-label's balance.

for (const organization of organizations) {
  const label = api.forOrganization(organization.id);
  for await (const release of label.list<{ title: string; status: string }>("/releases", { status: "LIVE" })) {
    console.log(organization.name, release.title);
  }
}

4. Hear from every sub-label#

Events belong to the organization they happened in, and an endpoint hears only its own organization's events. To follow every sub-label:

• register an endpoint for each sub-label (POST /webhooks with its header); they can all point at the same address, and each delivery's organizationId says which sub-label it is about; or
• read GET /events with each sub-label's header, for example after downtime.

What stays with your organization#

• The rate limit and usage: a key's calls count against its own organization, whichever sub-label they act for.
• The request log: it stays with the key's organization.
• The sandbox: sandbox keys can't act for sub-labels (SANDBOX_NO_SUB_LABELS); try the flow with your own organization first.

What each sub-label keeps#

• Review: each sub-label's releases are reviewed as its own, and automatic approval is set per account.
• Plan limits: a sub-label's releases count against its own limits.
• Money: statements, the balance and payouts are each sub-label's own.

On a white label, the smart link addresses the API returns use your own address once it is live (White label › Domains), for your sub-labels' releases too.

Errors you may meet#