# ABACUS # Chapter 1: Accounts — The Entity Structure An **Account** is the foundational entity in Abacus. Every dollar earned, every contract signed, every payment made — it all flows through an account. Think of it as the "canonical record" for a label, artist, or vendor relationship with Sony Music. --- ## What Is an Account? An account represents a **business entity** in the Abacus system. It could be: | Account Type | Example | |---------------------|----------------------------------------------| | **Label** | An indie label distributed through Sony | | **Artist** | A solo artist with a direct deal | | **Vendor** | A third-party rights holder | | **Publishing entity** | A publishing admin client | Every account has a unique **Account ID** (numeric) — this is the primary key used across all Abacus services. --- ## The 6 Components of an Account ### 1. Account Details The basic identity of the account: - **Name** — the legal or business name - **Account ID** — the internal numeric identifier - **Status** — active, inactive, etc. - **Agreement Type** — the broad category of deal (e.g. distribution, license, joint venture) --- ### 2. Payment Terms How and when the account gets paid: - **Payment frequency** — monthly, quarterly, etc. - **Payment threshold** — minimum balance required before a payment is triggered - **Payment method** — wire transfer, ACH, check, etc. - **Currency** — the currency in which the account is paid (e.g. USD, EUR, GBP) --- ### 3. Payment Eligibility A real-time flag that answers: **"Is this account eligible to receive a payment right now?"** Eligibility can be blocked by: - Missing or unverified **tax information** - An active **payment hold** - Incomplete **payee setup** (missing bank details) - Unrecouped **advance balance** --- ### 4. Tax Information Abacus tracks the account's tax profile: - **Tax ID type** — W-9 (U.S.), W-8 (foreign), etc. - **Withholding status** — whether Sony must withhold taxes before paying - **Tax country** — jurisdiction for treaty benefits > ⚠️ If tax info is missing or expired, the account will typically be **ineligible for payment** > and may have withholding applied. --- ### 5. Payees A payee is the **entity that actually receives the money**. An account can have one or more payees: - Each payee has their own **bank/payment details** - Payees can have **change history** (audit trail of updates) - A payee can be shared across multiple accounts (e.g. a label group) > Think of the **account** as *who earned the money* and the **payee** as *who the check is > written to*. --- ### 6. Activity Summary A high-level snapshot of the account's financial activity: - Total **revenue earned** across all periods - Outstanding **advance balance** - Current **ledger position** (positive = payable, negative = unrecouped) - Associated **contracts** count --- ## How Accounts Connect to Everything Else Account ``` ├── Contracts (1 or more) ├── Terms & Conditions (royalty rates) └── Advances (recoupable amounts) ├── Payees (who receives payment) ├── Tax Info (withholding rules) ├── Ledger Balance (net financial position) └── Statement Periods (monthly revenue snapshots) ``` One account can have **multiple contracts** — for example, a label might have separate contracts for streaming, physical distribution, and sync licensing. --- ## Key Concepts to Remember | Concept | Plain English | |------------------|-------------------------------------------------------------------------------| | **Account ID** | The unique number that identifies everything — always needed to look anything up | | **Payee ≠ Account** | The account earns money; the payee receives it — they can be different entities | | **Eligibility** | A real-time gate before any payment is released | | **Agreement Type** | Sets the broad commercial framework of the deal | | **Currency** | All financial figures are reported in the account's payee currency | --- ## What We Can Look Up Live With an **Account ID or name**, we can instantly pull: - Full account details & agreement type - Payment terms and eligibility status - Tax info and payee setup - All associated contracts - Current ledger balance --- # Chapter 2: Contracts & Terms — The Royalty Rate Structure A **Contract** is the legal and financial agreement between Sony Music and an account. It defines *how much* the account earns, *on what*, *where*, and *under what conditions*. Every royalty calculation in Abacus flows through a contract. --- ## What Is a Contract? A contract is the rulebook for royalty accounting. It answers: - What **royalty rate** does this account earn? - On which **platforms (stores/DSPs)** does that rate apply? - In which **countries/territories** does that rate apply? - For which **types of transactions** (streams, downloads, sync)? - Are there any **advances** to recoup before payment is released? Every contract belongs to exactly one **Account** and has a unique **Contract ID** (numeric). An account can have multiple contracts — for example, separate contracts for streaming, physical distribution, and sync licensing. --- ## The Anatomy of a Contract ``` Contract ├── Contract Details (name, status, dates, type) ├── Parties (who is bound by this contract) ├── Lifecycle (draft → active → expired) ├── Run Controller (accounting engine status) ├── Terms (1 or more rate schedules) │ └── Conditions (per-term rate rules) │ ├── Transaction Types (AEV, AEA, download, etc.) │ ├── Countries / Territories │ └── Stores / DSPs └── Advances (recoupable amounts tied to this contract) ``` --- ## Contract Details The top-level metadata of a contract: | Field | Description | |--------------------|------------------------------------------------------------------| | **Contract ID** | Unique numeric identifier — the primary key | | **Contract Name** | Human-readable label (e.g. "Artist Distribution Agreement 2023") | | **Status** | Active, Inactive, Draft, Expired | | **Start Date** | When the contract becomes effective | | **End Date** | When the contract expires (may be open-ended) | | **Contract Type** | Broad classification of the deal structure | --- ## Parties A contract has one or more **parties** — the entities formally bound by the agreement: - Typically includes the **label/artist** (account) and **Sony Music** as distributor - Each party has a defined **role** (e.g. licensor, licensee, administrator) - Parties are linked to their respective **Account IDs** in Abacus --- ## Contract Lifecycle Contracts move through a defined set of states: ``` Draft → Active → Expired / Terminated ``` | State | Meaning | |-----------------|---------------------------------------------------------------------| | **Draft** | Contract created but not yet in effect — no royalties calculated | | **Active** | Live contract — royalties are being calculated and accumulated | | **Expired** | Past end date — no new royalties, but history is preserved | | **Terminated** | Ended early — may have special settlement terms | --- ## Run Controller The **Run Controller** is the accounting engine's on/off switch for a contract. It determines whether Abacus will process royalties for this contract in a given statement period run. - **Enabled** — the contract participates in the next accounting run - **Disabled** — the contract is skipped (e.g. during audits or corrections) > ⚠️ A contract can be **Active** (legally) but have its Run Controller **Disabled** (operationally) — meaning no royalties will be calculated until it is re-enabled. --- ## Terms A **Term** is a rate schedule within a contract. Most contracts have at least one term, but complex deals can have many — each covering a different scenario. | Field | Description | |--------------------|--------------------------------------------------------------------| | **Term ID** | Unique numeric identifier for this term | | **Term Name** | Human-readable label (e.g. "Label Term", "Digital Term") | | **Term Type** | Category: Label Term, Track Term, Artist Term, etc. | | **Is Base Term** | Whether this is the default/fallback term when no other term matches | ### Base Term vs. Non-Base Term - The **Base Term** is the catch-all — it applies when no more specific term matches the transaction being evaluated. - **Non-base terms** are more specific and evaluated first based on their **priority**. --- ## Conditions A **Condition** is the core rate rule within a term. Each term can have multiple conditions, evaluated in **priority order** (lowest number = evaluated first). | Field | Description | |----------------------------------|---------------------------------------------------------| | **Condition Name** | Human-readable label for this rate rule (may be null) | | **Term Rate** | The artist/label royalty rate as a percentage (0–100%) | | **Commission** | Sony's share: `Commission = 100% − Term Rate` | | **Priority** | Evaluation order — lower number = higher priority | | **Applicable Transaction Types** | Which revenue categories this rate applies to | | **Applicable Countries** | Which territories this rate applies to | | **Applicable Stores** | Which DSPs/platforms this rate applies to | ### How Conditions Are Evaluated When a revenue event arrives (e.g. a Spotify stream in the US), Abacus evaluates conditions in priority order and applies the **first matching condition**: ``` Revenue Event (e.g. Spotify stream, US, AEA) │ ▼ Condition 1 (Priority 1) ── matches? ──► Apply rate → STOP │ no match ▼ Condition 2 (Priority 2) ── matches? ──► Apply rate → STOP │ no match ▼ Base Term Condition ────────────────────► Apply default rate ``` --- ## Transaction Types A **Transaction Type** defines the *category* of a revenue event. Each condition specifies which transaction types it covers. | Code | Full Name | Description | |---------|----------------------------------|------------------------------------------| | **AEA** | Ad-Enabled Audio Streams | Free-tier audio streams with ads | | **AEV** | Ad-Enabled Video Streams | Free-tier video streams with ads | | **ADA** | Ad-Disabled Audio Streams | Premium / subscription audio streams | | **ADV** | Ad-Disabled Video Streams | Premium / subscription video streams | | **DLS** | Downloads | Permanent digital download sales | | **SYN** | Sync License | Music licensed for film, TV, ads | | **PHY** | Physical | CD, vinyl, and other physical sales | > Transaction type codes are short identifiers (e.g. "AEV"). Their full names (e.g. "Ad-Enabled Video Streams") are resolved from the Abacus reference data. --- ## Advances An **Advance** is money paid to the account *upfront*, before it has been earned. It must be **recouped** (paid back from future royalties) before the account receives any further payment. | Field | Description | |------------------------|-----------------------------------------------------------------| | **Advance ID** | Unique numeric identifier | | **Amount** | The dollar amount advanced | | **Status** | Active, Fully Recouped, Written Off, etc. | | **Recoupment Status** | How much has been recouped vs. how much remains | | **Cross-Recoupment** | Whether this advance recoupes across multiple contracts | ### How Recoupment Works ``` Advance Paid: $100,000 │ ▼ Royalties Earned Each Period │ ▼ Royalties Applied to Advance Balance First │ ▼ Advance Balance: $100,000 → $80,000 → $50,000 → $0 │ ▼ Once Fully Recouped → Royalties Released as Payment ``` > Until the advance is fully recouped, the account's **ledger balance** will be negative (unrecouped), and **no payment** will be disbursed. --- ## Enriched Terms: The Full Picture When viewing a contract in Abacus, the terms are **enriched** — meaning transaction type IDs are resolved to their full codes and names, making it easy to understand exactly what each condition covers without needing a separate reference lookup. Example enriched condition: ``` Term: "Digital Streaming Term" Condition: "Premium Audio" ├── Term Rate: 80% ├── Commission: 20% ├── Priority: 1 ├── Transaction Types: ADA (Ad-Disabled Audio Streams), ADV (Ad-Disabled Video Streams) ├── Countries: All territories └── Stores: Spotify, Apple Music, Amazon Music ``` --- ## Key Concepts to Remember | Concept | Plain English | |-----------------------|--------------------------------------------------------------------------------------| | **Contract** | The rulebook — defines rates, scope, and advances for an account | | **Term** | A rate schedule within the contract — there can be many | | **Condition** | The actual rate rule — matched by transaction type, country, and store | | **Term Rate** | The percentage the account earns (e.g. 80%) | | **Commission** | Sony's percentage — always `100% − Term Rate` | | **Priority** | The order conditions are evaluated — lower = checked first | | **Base Term** | The catch-all fallback rate when no specific condition matches | | **Advance** | Upfront money that must be earned back before payments are released | | **Run Controller** | The on/off switch for whether a contract is processed in an accounting run | | **Transaction Type** | The category of revenue event (e.g. AEV = Ad-Enabled Video Stream) | --- ## How Contracts Connect to Other Entities ``` Account └── Contract ├── Parties → who is bound ├── Lifecycle → current state (Draft / Active / Expired) ├── Run Controller → is accounting enabled? ├── Terms │ └── Conditions │ ├── Transaction Types → what kind of revenue? │ ├── Countries → where in the world? │ └── Stores → which DSP/platform? └── Advances → unrecouped balance blocks payment ``` --- ## What We Can Look Up Live With a **Contract ID**, we can instantly pull: - Full contract details, status, and lifecycle state - All terms with enriched conditions (rates, transaction types, countries, stores) - All advances and their recoupment status - Parties bound by the contract - Run Controller status With a **Contract Name**, we can search for the contract and resolve its ID first. --- # Chapter 3: Statement Periods — The Accounting Calendar A **Statement Period** is the heartbeat of Abacus. It defines the time window in which revenue is collected, royalties are calculated, and balances are updated. Every dollar that flows through the system is stamped with a statement period. --- ## What Is a Statement Period? A statement period is a **monthly accounting window** — typically aligned with calendar months (e.g. "2024-01" = January 2024). It answers: - **When** was this revenue earned? - **Which accounting run** does it belong to? - **What is the current period** the system is processing? Every financial figure in Abacus — revenue, adjustments, advances, payments — is tied to a specific statement period. --- ## Statement Period Fields | Field | Description | |--------------------------|--------------------------------------------------------------------| | **Statement Period ID** | Unique numeric identifier — used internally across all services | | **Statement Period Name**| Human-readable label (e.g. "2024-01", "2024-06") | | **Status** | The current state of the period (see lifecycle below) | | **Start Date** | First day of the period (e.g. 2024-01-01) | | **End Date** | Last day of the period (e.g. 2024-01-31) | > ⚠️ **Important Rule:** The `statement_period_id` is an arbitrary number — it has no date > meaning. Never guess or calculate what period an ID represents. Always resolve it to a > `statement_period_name` using a tool call. --- ## Statement Period Lifecycle Each statement period moves through a defined sequence of states: ``` Upcoming → Open → Processing → Closed → Finalized ``` | State | What's Happening | |-----------------|---------------------------------------------------------------------------| | **Upcoming** | Future period — not yet active, no revenue being collected | | **Open** | Current active period — revenue is flowing in, adjustments can be made | | **Processing** | Accounting runs are executing — royalties being calculated | | **Closed** | Calculations complete — balances locked, payments being prepared | | **Finalized** | Fully complete — payments disbursed, period is immutable | ### What Can Happen in Each State | Action | Upcoming | Open | Processing | Closed | Finalized | |------------------------------|:--------:|:----:|:----------:|:------:|:---------:| | Revenue ingested | ❌ | ✅ | ❌ | ❌ | ❌ | | Adjustments submitted | ❌ | ✅ | ❌ | ❌ | ❌ | | Royalty calculations run | ❌ | ❌ | ✅ | ❌ | ❌ | | Balances updated | ❌ | ❌ | ✅ | ❌ | ❌ | | Payments prepared | ❌ | ❌ | ❌ | ✅ | ❌ | | Payments disbursed | ❌ | ❌ | ❌ | ❌ | ✅ | | Data is immutable | ❌ | ❌ | ❌ | ❌ | ✅ | --- ## The Monthly Cycle Here's how a typical month flows through Abacus: ``` Month Begins │ ▼ Statement Period Opens │ ← Revenue streams in from DSPs (Spotify, Apple Music, etc.) │ ← Manual adjustments can be submitted │ ← Advance draw-downs recorded ▼ Statement Period Moves to Processing │ ← Royalty engine runs contract terms against revenue │ ← Rates applied per condition (transaction type, country, store) │ ← Advance recoupment calculated │ ← Ledger balances updated ▼ Statement Period Closes │ ← Balances locked │ ← Payment eligibility evaluated per account │ ← Payment entities created for eligible accounts ▼ Statement Period Finalized │ ← Payments disbursed │ ← Period becomes read-only / immutable ▼ Next Month Opens ``` --- ## Activity Month vs. Statement Month This distinction matters for **retroactive adjustments**: | Concept | Meaning | |----------------------|----------------------------------------------------------------------| | **Activity Month** | When the revenue event *actually happened* (e.g. streams in March) | | **Statement Month** | Which accounting period the revenue is *applied to* (e.g. May) | These are usually the same — March revenue lands in the March statement period. But they can differ when: - **Late-arriving data** — a DSP reports March streams in May - **Retroactive adjustments** — correcting a past error in a current period - **Out-of-period corrections** — applying a credit for Q1 in a Q3 statement period > When creating adjustments, both Activity Month/Year and Statement Month/Year must be > specified. If the intent is unclear, always ask the user to confirm both. --- ## Revenue Within a Statement Period Each statement period collects revenue from multiple sources: ``` Statement Period: 2024-06 ├── Revenue by Store │ ├── Spotify → $50,000 │ ├── Apple Music → $30,000 │ ├── Amazon Music → $10,000 │ └── YouTube Music → $5,000 ├── Revenue by Artist │ ├── Artist A → $40,000 │ ├── Artist B → $35,000 │ └── Artist C → $20,000 └── Revenue by Transaction Type ├── ADA (Premium Audio) → $60,000 ├── AEA (Free Audio) → $20,000 └── AEV (Free Video) → $15,000 ``` Revenue can be sliced by: - **Store / DSP** — which platform generated the revenue - **Artist** — which artist's catalog earned it - **Transaction Type** — what kind of consumption (stream, download, sync) - **Country / Territory** — where the listener was located --- ## Payment Entities When a statement period closes, Abacus creates **Payment Entities** — these are the individual payment records for each eligible account: | Field | Description | |---------------------|--------------------------------------------------------------------| | **Account** | The account receiving payment | | **Payable Amount** | Net amount after recoupment, reserves, and holds | | **Payment Status** | Pending, Approved, Disbursed, Failed | | **Payment Method** | Wire, ACH, Check — from the account's payment terms | ### Payment Eligibility Check Before a payment entity is created, Abacus checks: 1. ✅ Account has valid **tax information** 2. ✅ Account has valid **payee / bank details** 3. ✅ No active **payment holds** 4. ✅ Balance exceeds **payment threshold** 5. ✅ Advance is **fully recouped** (or no advance exists) If any check fails, the account is **ineligible** — no payment entity is created, and the balance rolls forward to the next period. --- ## Statement Period vs. Accounting Period These are related but distinct concepts: | Concept | Scope | |------------------------|--------------------------------------------------------------------| | **Statement Period** | The monthly window visible to accounts — revenue, statements, payments | | **Accounting Period** | The internal processing window — may include sub-runs, corrections, and re-runs | For most purposes, they align 1:1. The distinction matters mainly for internal accounting operations (re-runs, corrections, audit trails). --- ## Key Concepts to Remember | Concept | Plain English | |----------------------------------|-----------------------------------------------------------------------------| | **Statement Period** | A monthly accounting window — the time bucket for all financial activity | | **Statement Period ID** | An arbitrary number — never guess dates from it, always resolve via tool | | **Statement Period Name** | The human-readable label (e.g. "2024-01") — this is the date reference | | **Open Period** | The currently active period accepting revenue and adjustments | | **Activity Month vs. Statement Month** | When revenue happened vs. which period it's booked to | | **Payment Entity** | The payment record created when a period closes for an eligible account | | **Immutability** | Once finalized, a period's data cannot be changed — corrections go to a new period | --- ## How Statement Periods Connect to Other Entities ``` Statement Period ├── Revenue │ ├── By Store (DSP) │ ├── By Artist │ └── By Transaction Type ├── Adjustments (manual credits/debits applied in this period) ├── Advance Recoupment (portion of royalties applied to advances) ├── Ledger Updates (balance changes for each account/contract) └── Payment Entities (payments created at period close) ├── Eligibility Check │ ├── Tax Info ✓ │ ├── Payee Setup ✓ │ ├── No Holds ✓ │ ├── Threshold Met ✓ │ └── Advance Recouped ✓ └── Disbursement ``` --- ## What We Can Look Up Live With no parameters needed: - **Current statement period** — what period is active right now With an **Account ID**: - All statement periods with per-period revenue - Revenue breakdown by store, artist, and transaction type for any period - Payment entity status for any period - Activity summary across all periods With a **Statement Period ID**: - Revenue filtered to that specific period - Payment entities and their processing status --- # Chapter 4: Revenue — How Earnings Flow In **Revenue** is the money earned from the consumption of music — streams, downloads, sync licenses, physical sales, and more. It is the primary input to Abacus and the foundation of every royalty calculation, ledger balance, and payment. --- ## What Is Revenue in Abacus? Revenue represents the **dollars earned** when someone streams a song, buys a download, licenses a track for a movie, or purchases a physical album. It flows into Abacus from Digital Service Providers (DSPs) and other sources, gets matched to accounts and contracts, and is processed through the royalty engine. Revenue answers: - **How much** was earned? - **Where** was it earned (which store/DSP)? - **Who** earned it (which artist/account)? - **What kind** of consumption generated it (stream, download, sync)? - **When** was it earned (which statement period)? > ⚠️ **Revenue ≠ Streams.** Revenue is money earned (dollars). Stream counts (how many > times a track was played) are a separate metric available only in Snowflake — the > financial service returns dollars only, not play quantities. --- ## The Revenue Pipeline ``` DSPs Report Revenue (Spotify, Apple Music, YouTube, Amazon, etc.) │ ▼ Revenue Ingested into Abacus │ ← Matched to Account, Contract, Artist, Product │ ← Tagged with Store, Country, Transaction Type ▼ Revenue Lands in Statement Period │ ← Gross revenue recorded (before Sony's commission) │ ← Net revenue calculated (after commission applied via contract terms) ▼ Royalty Engine Processes │ ← Contract terms evaluated │ ← Advance recoupment applied │ ← Ledger balance updated ▼ Revenue Available on Statement ``` --- ## Gross Revenue vs. Net Revenue Every revenue figure in Abacus has two sides: | Metric | Definition | |--------------------|--------------------------------------------------------------------| | **Gross Revenue** | Total money earned *before* Sony's distribution commission | | **Net Revenue** | Money earned *after* commission — this is what the account keeps | ### The Math ``` Net Revenue = Gross Revenue × (Term Rate ÷ 100) Commission = Gross Revenue × (Commission Rate ÷ 100) Example: Gross Revenue: $10,000 Term Rate: 80% Commission Rate: 20% Net Revenue: $10,000 × 0.80 = $8,000 (account keeps) Commission: $10,000 × 0.20 = $2,000 (Sony keeps) ``` > **Always report both gross and net** when presenting revenue figures. Always include > the **currency code** (e.g. USD, EUR, GBP) — never present a number without its currency. --- ## Revenue Dimensions Revenue can be sliced across multiple dimensions. Think of each dimension as a different lens on the same pool of money: ### By Store (DSP) Which platform generated the revenue: | Store | Example Revenue | |-----------------|-----------------| | Spotify | $50,000 | | Apple Music | $30,000 | | Amazon Music | $10,000 | | YouTube Music | $8,000 | | Deezer | $3,000 | | Tidal | $2,000 | > When querying store-level revenue, the default limit is 5 stores. Always pass > `limit: 100` when the user asks for "all stores" or a "full breakdown" — and > explicitly say "Top N stores" when showing a subset. --- ### By Artist Which artist's catalog earned the revenue: | Artist | Example Revenue | |-----------------|-----------------| | Artist A | $45,000 | | Artist B | $30,000 | | Artist C | $15,000 | | Various Artists | $10,000 | > A single account (e.g. a label) can have revenue from many artists. --- ### By Transaction Type What kind of consumption generated the revenue: | Code | Full Name | Typical Revenue Share | |---------|-----------------------------|----------------------| | **ADA** | Ad-Disabled Audio Streams | Highest (premium) | | **AEA** | Ad-Enabled Audio Streams | Moderate (free tier) | | **ADV** | Ad-Disabled Video Streams | Moderate | | **AEV** | Ad-Enabled Video Streams | Lower | | **DLS** | Downloads | Varies | | **SYN** | Sync License | Varies (lump sums) | | **PHY** | Physical | Varies | --- ### By Country / Territory Where in the world the consumption happened: | Territory | Example Revenue | |-----------------|-----------------| | United States | $40,000 | | United Kingdom | $15,000 | | Germany | $10,000 | | Brazil | $8,000 | | Japan | $7,000 | --- ### By Statement Period When the revenue was earned (which accounting month): | Period | Revenue | |----------|------------| | 2024-01 | $90,000 | | 2024-02 | $95,000 | | 2024-03 | $102,000 | | 2024-04 | $88,000 | | 2024-05 | $110,000 | | 2024-06 | $105,000 | --- ## Revenue Currency All revenue figures are reported in the account's **payee currency** — the currency specified in the account's payment terms. - A US-based account → revenue reported in **USD** - A UK-based account → revenue reported in **GBP** - A Japan-based account → revenue reported in **JPY** The `account_payee_currency` field identifies which currency applies. **Never present a revenue figure without its currency code.** --- ## Revenue Totals vs. Per-Item Figures Abacus provides revenue at multiple levels of aggregation: ``` Account-Level Total (all revenue for the account) ├── Per-Period Totals (revenue per statement period) │ ├── Per-Store Revenue (Spotify, Apple Music, etc.) │ ├── Per-Artist Revenue (Artist A, Artist B, etc.) │ └── Per-Transaction-Type Revenue (ADA, AEA, etc.) └── All-Time Totals (cumulative across all periods) ``` > **Always use the `totals` object** for account-level totals rather than manually summing > individual items. Revenue data may be paginated — summing a partial page will produce > incorrect totals. --- ## Revenue vs. Streams vs. Payments These three concepts are related but distinct: | Concept | What It Is | Where It Lives | Unit | |--------------|-----------------------------------|-------------------------|---------------| | **Revenue** | Money earned from consumption | Financial service | Dollars ($) | | **Streams** | Number of times content was played| Snowflake only | Count (#) | | **Payments** | Money actually sent to the account| Payment service | Dollars ($) | ### Revenue → Payments Path Not all revenue becomes a payment immediately. The path from earning to payment is: ``` Revenue Earned (Gross) │ ▼ Commission Deducted → Net Revenue │ ▼ Advance Recoupment Applied (if applicable) │ ▼ Reserves Withheld (if applicable) │ ▼ Adjustments Applied (credits/debits) │ ▼ Payable Balance │ ▼ Eligibility Check (tax, payee, holds, threshold) │ ▼ Payment Disbursed ``` --- ## Revenue Sources Revenue enters Abacus from various channels: ### Digital (DSP) Revenue The bulk of modern revenue — reported by streaming platforms: - **Spotify** — subscription and ad-supported streams - **Apple Music** — subscription streams - **Amazon Music** — subscription and ad-supported streams - **YouTube / YouTube Music** — ad-supported and premium streams - **Deezer, Tidal, Pandora** — and many more Each DSP reports revenue with: - Track / product identifiers (ISRC, UPC) - Territory of consumption - Transaction type (premium vs. free, audio vs. video) - Revenue amount ### Physical Revenue Revenue from physical product sales: - **CDs, vinyl, cassettes** - Reported with UPC identifiers - May include manufacturing costs, returns, and reserves ### Sync Revenue Revenue from licensing music for use in: - **Film, TV, commercials, video games** - Typically reported as lump-sum license fees - May have different contract terms than streaming ### Other Revenue - **Performance royalties** — from public performance / broadcasting - **Mechanical royalties** — from reproduction rights - **Master license fees** — for use of the master recording --- ## Revenue Timing Revenue doesn't arrive in real-time. There is always a **lag** between when music is consumed and when the revenue appears in Abacus: ``` Music Consumed (e.g. Spotify stream in January) │ ▼ ~2-3 month lag DSP Reports Revenue to Sony (e.g. March) │ ▼ Revenue Ingested into Statement Period (e.g. March or April period) │ ▼ Royalties Calculated (during Processing phase) │ ▼ Payment Disbursed (at period close) ``` > This lag means that the revenue in the "2024-06" statement period does **not** > necessarily represent music consumed in June — it represents revenue **reported** > by DSPs during that period, which may cover consumption from earlier months. --- ## Key Concepts to Remember | Concept | Plain English | |----------------------------------|------------------------------------------------------------------------------| | **Revenue** | Money earned from music consumption — always in dollars, not stream counts | | **Gross Revenue** | Total before commission — the full pie | | **Net Revenue** | After commission — what the account keeps | | **Payee Currency** | All figures reported in the account's designated currency | | **Revenue ≠ Streams** | Revenue = dollars (Financial service). Streams = counts (Snowflake only) | | **Revenue ≠ Payments** | Revenue is earned; payments are disbursed — recoupment, reserves, and holds intervene | | **Totals Object** | Always use it for account-level totals — don't manually sum paginated data | | **Revenue Lag** | 2-3 months between consumption and revenue appearing in Abacus | | **Activity Month ≠ Statement Month** | When consumption happened vs. when revenue was booked | --- ## How Revenue Connects to Other Entities ``` Revenue ├── Account → who earned it ├── Contract → which deal governs the rate │ └── Term / Condition → which rate was applied ├── Statement Period → when it was booked ├── Store / DSP → which platform reported it ├── Artist → whose catalog generated it ├── Transaction Type → what kind of consumption ├── Country → where the listener was └── Product → which track/album (ISRC/UPC) ``` --- ## What We Can Look Up Live With an **Account ID**: - Revenue summary across all statement periods - Revenue breakdown by store (DSP) — per period or all-time - Revenue breakdown by artist — per period or all-time - Per-period revenue totals with gross and net figures With an **Account ID + Statement Period ID**: - Revenue filtered to a specific period - Store-level and artist-level breakdown for that period For **stream counts** (not dollars): - Use Snowflake — the financial service does not have play quantities For **revenue trends and analytics**: - Use Snowflake for time-series analysis, comparisons, and custom aggregations --- # Chapter 6: Advances & Recoupment — Upfront Money and Earning It Back An **Advance** is money paid to an account before it has been earned through royalties. It's an investment by Sony Music in an artist or label — and it must be **recouped** (earned back) from future royalty earnings before any payments are released. Advances are one of the most critical financial mechanisms in Abacus. --- ## What Is an Advance? An advance is essentially a **loan against future royalties**. When Sony signs an artist or label, they may pay an upfront sum — $50,000, $500,000, $5,000,000 — as a signing bonus, marketing fund, or working capital. That money doesn't disappear. It sits on the **ledger as a negative balance** and must be paid back from the account's future earnings. ``` Day 1: Sony pays artist $100,000 advance Ledger Balance: −$100,000 Month 1: Artist earns $15,000 in royalties Royalties applied to advance → Ledger Balance: −$85,000 Artist receives: $0 Month 6: Artist has earned $100,000 cumulative Advance fully recouped → Ledger Balance: $0 Artist receives: $0 (just broke even) Month 7: Artist earns $12,000 No advance to recoup → Ledger Balance: +$12,000 Artist receives: $12,000 ✅ ``` --- ## Advance Lifecycle Every advance moves through a defined set of states: ``` Created → Active → Recouping → Fully Recouped → Written Off (in some cases) ``` | State | Meaning | |---------------------|-----------------------------------------------------------------------| | **Created** | Advance record exists but hasn't been activated yet | | **Active** | Advance is live — recoupment begins with the next accounting run | | **Recouping** | Royalties are being applied against the advance balance each period | | **Fully Recouped** | The entire advance has been earned back — account is now payable | | **Written Off** | Sony has decided to forgive the remaining balance (rare) | --- ## Advance Fields | Field | Description | |--------------------------|---------------------------------------------------------------------| | **Advance ID** | Unique numeric identifier | | **Amount** | The original advance amount (e.g. $100,000) | | **Currency** | Currency of the advance (matches the account's payee currency) | | **Status** | Current lifecycle state (Active, Fully Recouped, Written Off, etc.) | | **Contract ID** | The contract this advance is tied to | | **Recouped Amount** | How much has been earned back so far | | **Unrecouped Balance** | Remaining amount: `Amount − Recouped` | | **Start Date** | When the advance was activated | | **Cross-Recoupment** | Whether recoupment spans multiple contracts | --- ## How Recoupment Works Recoupment is the process of applying earned royalties to pay down an advance balance. It happens automatically during each statement period's accounting run. ### The Recoupment Flow ``` Statement Period Opens │ ▼ Revenue Earned for the Period │ (e.g. $15,000 net revenue) ▼ Royalty Engine Checks: Does this contract have an unrecouped advance? │ ├── YES → Apply royalties to advance balance first │ Advance Balance: −$85,000 → −$70,000 │ Payment to Account: $0 │ └── NO → Royalties go to payable balance Payment to Account: $15,000 ``` ### Recoupment Priority When royalties are earned, they are applied in this order: ``` 1. Advance Recoupment (if unrecouped balance exists) 2. Cross-Recoupment (if enabled — see below) 3. Reserve Withholding (if applicable) 4. Payable Balance (what's left goes to the account) ``` --- ## Single-Contract Recoupment The simplest case: one advance tied to one contract. ``` Contract A: Advance = $100,000 │ ▼ Only revenue earned under Contract A is used to recoup │ ▼ Contract A Revenue: $20,000/month │ ▼ Month 1: Balance −$80,000 Month 2: Balance −$60,000 Month 3: Balance −$40,000 Month 4: Balance −$20,000 Month 5: Balance $0 ← Fully Recouped ✅ Month 6: Balance +$20,000 → Payment Released ``` --- ## Cross-Recoupment **Cross-recoupment** allows an advance on one contract to be recouped using revenue from **multiple contracts** on the same account. This is a more aggressive recoupment strategy that benefits the label/distributor. ``` Account has two contracts: ├── Contract A: Advance = $100,000 (cross-recoupment enabled) └── Contract B: No advance Contract A Revenue: $10,000/month Contract B Revenue: $15,000/month WITHOUT Cross-Recoupment: Only Contract A's $10,000/month applies → 10 months to recoup WITH Cross-Recoupment: Both contracts' $25,000/month applies → 4 months to recoup ``` ### Cross-Recoupment Rules | Rule | Description | |-----------------------------------------|----------------------------------------------------------| | Must be **explicitly enabled** | Not all advances allow cross-recoupment | | Applies within the **same account** | Cannot cross-recoup across different accounts | | Contract terms govern eligibility | The contract specifies which contracts participate | | Revenue priority may apply | Some structures prioritize the advance's own contract first | --- ## Multiple Advances An account can have **multiple advances** across different contracts or even on the same contract: ``` Account Balance Sheet: ├── Contract A │ ├── Advance 1: $50,000 (Signing Bonus) — Active, Recouping │ └── Advance 2: $30,000 (Marketing Fund) — Active, Recouping ├── Contract B │ └── Advance 3: $100,000 (Label Advance) — Active, Recouping └── Contract C └── No advance — revenue flows directly to payment ``` ### Advance Stacking When multiple advances exist on the same contract, they may be recouped: - **Sequentially** — Advance 1 must be fully recouped before Advance 2 begins - **Simultaneously** — royalties are split proportionally across all active advances - The specific behavior depends on the **contract terms** --- ## Advance Draw-Downs An advance doesn't have to be paid in one lump sum. A **draw-down** is a partial disbursement of a larger committed advance: ``` Committed Advance: $500,000 Draw-Down 1: $200,000 (upon signing) Draw-Down 2: $150,000 (upon album delivery) Draw-Down 3: $150,000 (upon commercial release) Total Drawn: $500,000 Recoupment begins on the total drawn amount ``` Each draw-down is recorded as a separate ledger event, and the advance balance increases with each disbursement. --- ## Advance Recoupment and the Ledger The advance creates a direct relationship between the advance balance and the ledger balance: ``` Advance Issued: −$100,000 (ledger goes negative) Period 1: Revenue +$20,000 → Recouped $20,000 → Ledger: −$80,000 Period 2: Revenue +$25,000 → Recouped $25,000 → Ledger: −$55,000 Period 3: Revenue +$30,000 → Recouped $30,000 → Ledger: −$25,000 Period 4: Revenue +$25,000 → Recouped $25,000 → Ledger: $0 Period 5: Revenue +$22,000 → Recouped $0 → Ledger: +$22,000 ← Payable ``` > The **ledger balance** is the ultimate arbiter. Even if the advance is technically > "fully recouped," the account won't receive payment until the ledger balance is > positive AND all eligibility checks pass. --- ## Recoupment Reporting Abacus provides visibility into recoupment at multiple levels: ### Per-Advance View ``` Advance ID: 12345 Original Amount: $100,000 Recouped to Date: $75,000 Unrecouped Balance: $25,000 Status: Recouping % Recouped: 75% ``` ### Per-Contract View ``` Contract ID: 6789 Total Advances: $200,000 Total Recouped: $150,000 Net Advance Balance: −$50,000 ``` ### Per-Account View ``` Account ID: 1234 Total Advances (all contracts): $350,000 Total Recouped (all contracts): $280,000 Net Advance Position: −$70,000 Account Ledger Balance: −$70,000 (not payable) ``` --- ## Advance Types and Adjustment Categories Advances interact with several adjustment types in Abacus: | Adjustment Type | Description | |------------------------------|----------------------------------------------------------------| | **Advance (Draw-Down)** | Recording a new advance disbursement | | **Advance Recoupment** | Manual recoupment adjustment (outside normal processing) | | **Cross Recoupment** | Manual cross-contract recoupment adjustment | | **Label Advance** | Advance specific to a label-level deal | | **Publisher Advance** | Advance specific to a publishing deal | | **Non-Recoupable Advance Credit** | An advance that does NOT need to be recouped (rare — a gift) | | **Non-Recoupable Bonus** | A bonus payment that doesn't affect recoupment | --- ## Recoupment Scenarios ### Scenario 1: Simple Recoupment ``` Single contract, single advance, steady revenue → Straightforward: revenue chips away at advance each month → Once recouped, payments begin flowing ``` ### Scenario 2: Slow Recoupment ``` Large advance, modest revenue → May take years to recoup → Account remains in negative balance / unrecouped state → No payments disbursed until recouped (or advance written off) ``` ### Scenario 3: Cross-Recoupment Acceleration ``` Advance on Contract A, but Contract B is a hit → Cross-recoupment pulls Contract B revenue to pay down Contract A's advance → Faster recoupment, but artist earns less from Contract B in the short term ``` ### Scenario 4: Multiple Advances Stacked ``` Advance 1: $50,000 (2022) Advance 2: $75,000 (2023) Advance 3: $100,000 (2024) → Total to recoup: $225,000 → Revenue must cover all three before payments begin → Recoupment order depends on contract terms ``` ### Scenario 5: Advance Write-Off ``` Advance: $200,000 Revenue after 5 years: $80,000 Decision: Write off remaining $120,000 → Ledger balance goes to $0 → Future revenue flows directly to payment → Write-off is a business decision, not automatic ``` --- ## Key Concepts to Remember | Concept | Plain English | |--------------------------------------|--------------------------------------------------------------------------------| | **Advance** | Upfront money paid to the account — must be earned back | | **Recoupment** | The process of applying royalties to pay down an advance | | **Unrecouped Balance** | The remaining advance amount not yet earned back | | **Fully Recouped** | The advance has been completely paid back — payments can begin | | **Cross-Recoupment** | Using revenue from multiple contracts to pay down a single advance | | **Draw-Down** | A partial disbursement of a larger committed advance | | **Write-Off** | Sony forgives the remaining unrecouped balance (business decision) | | **Non-Recoupable** | An advance or bonus that doesn't need to be earned back (rare) | | **Recoupment Priority** | Advances are paid back before the account receives any payment | | **Ledger Balance = Advance Position**| The ledger balance directly reflects the advance recoupment state | --- ## How Advances Connect to Other Entities ``` Advance ├── Contract (which deal the advance belongs to) │ └── Cross-Recoupment → other contracts on the same account ├── Account (who received the advance) ├── Ledger Balance (advance creates negative balance) │ └── Recoupment reduces the negative over time ├── Statement Periods (recoupment happens each period) │ └── Revenue earned → applied to advance → balance updated ├── Adjustments │ ├── Advance (Draw-Down) → new advance disbursements │ ├── Advance Recoupment → manual recoupment corrections │ └── Non-Recoupable Credit → advances that don't recoup └── Payment Eligibility └── Advance must be fully recouped before payment is released ``` --- ## What We Can Look Up Live With a **Contract ID**: - All advances tied to the contract (active, recouped, written off) - Recoupment status and unrecouped balance for each advance - Cross-recoupment configuration With an **Account ID**: - Total advance position across all contracts - Current ledger balance (reflects advance recoupment state) - Payable balance (shows impact of unrecouped advances) - Payment eligibility (will flag if advance is blocking payment) With an **Account ID + Contract ID**: - Per-contract advance breakdown - Advance recoupment history over time --- # Chapter 7: Payments & Holds — When and Why Money Is Released **Payments** are the final step in the royalty lifecycle — the moment money moves from Abacus to the account holder's bank. But between earning revenue and receiving a payment, there are eligibility gates, holds, thresholds, and timing rules that determine **when** (and **whether**) money is actually released. --- ## What Is a Payment? A payment is the **disbursement of the payable balance** from an account's ledger to the account's designated payee. It's the culmination of the entire royalty process: ``` Music Consumed → Revenue Earned → Royalties Calculated → Advance Recouped → Reserves Applied → Eligibility Verified → Payment Disbursed ✅ ``` A payment is created at the close of each statement period for every eligible account. If the account is not eligible, the balance **rolls forward** to the next period. --- ## The Payment Process ### Step-by-Step Flow ``` Statement Period Closes │ ▼ Abacus Evaluates Each Account │ ▼ Step 1: Calculate Payable Balance │ Net Revenue − Advances − Reserves ± Adjustments − Prior Payments │ ▼ Step 2: Check Payment Threshold │ Is the balance ≥ the minimum payment amount? │ (e.g. $100 minimum, $50 minimum — defined in payment terms) │ ├── NO → Balance rolls forward. No payment created. │ ▼ Step 3: Check Payment Eligibility │ ├── Valid tax information? ✓ │ ├── Valid payee / bank details? ✓ │ ├── No active payment holds? ✓ │ └── Advance fully recouped? ✓ │ ├── ANY CHECK FAILS → Balance rolls forward. No payment created. │ ▼ Step 4: Create Payment Entity │ Amount, method, payee, currency all determined │ ▼ Step 5: Payment Approved & Disbursed │ Money sent via wire, ACH, or check │ ▼ Step 6: Ledger Updated Balance reduced by payment amount ``` --- ## Payment Terms Every account has **Payment Terms** that define the rules of disbursement: | Field | Description | |--------------------------|----------------------------------------------------------------------| | **Payment Frequency** | How often payments are made: monthly, quarterly, semi-annually | | **Payment Threshold** | Minimum balance required to trigger a payment (e.g. $100) | | **Payment Method** | How the money is sent: wire transfer, ACH, check | | **Payment Currency** | The currency of disbursement (account's payee currency) | | **Payment Delay** | Optional delay period after period close before payment is released | ### Payment Frequency | Frequency | Payment Cycle | |-------------------|------------------------------------------------------------------| | **Monthly** | Payment evaluated every statement period (most common) | | **Quarterly** | Payment evaluated every 3 periods | | **Semi-Annual** | Payment evaluated every 6 periods | | **Annual** | Payment evaluated once per year | > If an account is on quarterly frequency, revenue accumulates for 3 months before > a payment is evaluated — even if the balance exceeds the threshold in month 1. ### Payment Threshold The minimum payable balance required to trigger a disbursement: ``` Threshold: $100 Period 1: Balance = $45 → Below threshold → No payment, rolls forward Period 2: Balance = $92 → Below threshold → No payment, rolls forward Period 3: Balance = $140 → Above threshold → Payment of $140 created ✅ ``` --- ## Payment Methods | Method | Description | Speed | |--------------------|----------------------------------------------------------|-------------| | **Wire Transfer** | Bank-to-bank electronic transfer — international capable | 1-5 days | | **ACH** | U.S. domestic electronic transfer | 2-3 days | | **Check** | Physical check mailed to the payee | 7-14 days | > The payment method is set in the account's payment terms and linked to the > **payee's bank details**. If bank details are missing or invalid, the account > becomes ineligible for payment. --- ## Payment Eligibility Before any payment is created, Abacus runs a comprehensive eligibility check. **All conditions must pass** — a single failure blocks the payment. ### The Five Eligibility Gates ``` Gate 1: Tax Information ─────── Is W-9/W-8 on file and valid? │ Gate 2: Payee Setup ─────────── Are bank details complete and verified? │ Gate 3: Payment Holds ───────── Are there any active holds on the account? │ Gate 4: Payment Threshold ───── Is the balance ≥ minimum payment amount? │ Gate 5: Advance Recoupment ──── Is the advance fully recouped (or no advance)? │ ▼ ALL PASS → Payment Entity Created ✅ ANY FAIL → Balance Rolls Forward ❌ ``` ### Eligibility Status | Status | Meaning | |------------------|----------------------------------------------------------------------| | **Eligible** | All gates pass — payment will be created at period close | | **Ineligible** | One or more gates failed — see reason for details | > The **ineligibility reason** field explains exactly which gate failed — > e.g. "Missing tax documentation", "Payment hold active", "Below threshold". --- ## Payment Holds A **Payment Hold** is the most common reason an otherwise-ready account doesn't receive payment. It's a deliberate freeze placed on the account — the balance exists but cannot be disbursed. ### Hold Types | Hold Type | Reason | Who Sets It | |--------------------------|------------------------------------------------------------|-----------------| | **Tax Hold** | Missing, expired, or unverified tax documentation | Automated | | **Legal Hold** | Active legal dispute, litigation, or audit | Legal team | | **Contractual Hold** | Contract requires conditions to be met before payment | Business Affairs| | **Administrative Hold** | Account under internal review or investigation | Operations | | **Payee Hold** | Missing or invalid bank/payment details | Automated | | **Bankruptcy Hold** | Account holder is in bankruptcy proceedings | Legal team | | **Dispute Hold** | Ownership or royalty split dispute pending resolution | Operations | ### Hold Lifecycle ``` Hold Placed (reason documented) │ ▼ Account Marked Ineligible for Payment │ Balance continues to accumulate but is not disbursed ▼ Issue Resolved (tax filed, dispute settled, etc.) │ ▼ Hold Removed (documented with timestamp) │ ▼ Account Re-Evaluated for Eligibility │ ▼ Next Period Close → Payment Created (if all other gates pass) ``` ### Hold History Every hold placement and removal is tracked in an **audit trail**: | Event | Timestamp | Hold Type | Placed By | Reason | |-----------------|----------------------|-------------|-------------|---------------------| | Hold Placed | 2024-01-15 09:30:00 | Tax Hold | System | W-9 expired | | Hold Removed | 2024-03-02 14:15:00 | Tax Hold | Tax Team | New W-9 received | | Hold Placed | 2024-06-01 11:00:00 | Legal Hold | Legal Dept | Audit in progress | --- ## Payment Entities When a payment is approved, a **Payment Entity** is created — this is the actual payment record in the system. | Field | Description | |----------------------|-------------------------------------------------------------------| | **Account** | The account receiving the payment | | **Payee** | The entity receiving the funds (may differ from the account) | | **Amount** | The dollar amount being disbursed | | **Currency** | Payment currency (from payment terms) | | **Payment Method** | Wire, ACH, or Check | | **Status** | Pending → Approved → Disbursed → Completed (or Failed) | | **Statement Period** | The period this payment belongs to | ### Payment Entity States ``` Pending → Approved → Disbursed → Completed → Failed (with reason) ``` | State | Meaning | |----------------|----------------------------------------------------------------------| | **Pending** | Payment created, awaiting approval | | **Approved** | Payment approved for disbursement | | **Disbursed** | Funds sent to the payee's bank account | | **Completed** | Funds confirmed received — payment cycle complete | | **Failed** | Payment failed (e.g. invalid bank details, rejected wire) | --- ## Failed Payments When a payment fails, the funds are **returned to the ledger** and the balance rolls forward: ``` Payment Disbursed: $50,000 │ ▼ Bank Rejects Wire (invalid account number) │ ▼ Payment Status: Failed │ ▼ $50,000 Returned to Ledger Balance │ ▼ Account Flagged: Payee Hold (invalid bank details) │ ▼ Balance Available for Next Period (once hold resolved) ``` Common failure reasons: - Invalid or outdated bank account details - Bank account closed - Regulatory block (sanctions, compliance) - Wire transfer rejected by intermediary bank - Check returned / undeliverable --- ## Balance Roll-Forward When a payment is **not created** (due to threshold, hold, or ineligibility), the balance doesn't disappear — it **rolls forward** to the next statement period: ``` Period 2024-01: Balance $80 → Below $100 threshold → No payment → Rolls forward Period 2024-02: Balance $80 + $60 new = $140 → Above threshold → Payment created ✅ ``` ``` Period 2024-03: Balance $200 → Tax Hold active → No payment → Rolls forward Period 2024-04: Balance $200 + $150 new = $350 → Tax Hold still active → Rolls forward Period 2024-05: Tax Hold removed → Balance $350 + $120 new = $470 → Payment created ✅ ``` > The balance is **never lost** — it always rolls forward until conditions are met > for disbursement. The only way a balance decreases without payment is through > adjustments (debits) or advance recoupment. --- ## Payment Timing ### When Payments Happen ``` Statement Period Closes (e.g. end of January) │ ▼ ~2-4 weeks processing Payment Entities Created and Approved │ ▼ ~1-5 business days Funds Disbursed (wire/ACH/check) │ ▼ ~1-14 days (depending on method) Funds Arrive in Payee's Bank Account ``` ### Typical Timeline | Event | Approximate Timing | |---------------------------------|-------------------------------------------| | Period closes | End of calendar month | | Royalty calculations complete | +1-2 weeks | | Payment entities created | +2-3 weeks | | Payments approved | +3-4 weeks | | Funds disbursed | +4-5 weeks after period close | | Funds received (wire/ACH) | +1-3 business days after disbursement | | Funds received (check) | +7-14 days after disbursement | > These are approximate timelines. Actual timing varies by region, payment method, > and internal processing schedules. --- ## What's Available vs. What's Not It's important to understand the boundary of what Abacus exposes: | Data Point | Available? | Tool / Method | |-----------------------------------------|:----------:|--------------------------------------------| | **Payment eligibility status** | ✅ | `account_overview_skill` | | **Payment holds (active & history)** | ✅ | Payment hold tools | | **Payable balance per contract** | ✅ | Ledger tools | | **Payment entity status per period** | ✅ | Payment entity tools | | **Payment terms (frequency, threshold)**| ✅ | `account_overview_skill` | | **Bank transfer details (wire refs)** | ❌ | Not available — contact account manager | | **Full payment disbursement history** | ❌ | Not available — use platform payments page | | **Check tracking / delivery status** | ❌ | Not available — contact account manager | --- ## Key Concepts to Remember | Concept | Plain English | |--------------------------------------|------------------------------------------------------------------------------| | **Payment** | Money sent from Abacus to the account's designated payee | | **Payable Balance** | The amount eligible for disbursement after all deductions | | **Payment Threshold** | Minimum balance required to trigger a payment | | **Payment Frequency** | How often payments are evaluated (monthly, quarterly, etc.) | | **Payment Eligibility** | All five gates must pass before a payment is created | | **Payment Hold** | A freeze that blocks payment — balance exists but can't be sent | | **Balance Roll-Forward** | Unpaid balance carries to the next period — money is never lost | | **Payment Entity** | The actual payment record: amount, method, status, payee | | **Failed Payment** | Funds returned to ledger, account flagged, balance rolls forward | | **Payment ≠ Revenue** | Revenue is earned; payment is disbursed — they are separated by time and gates | --- ## How Payments Connect to Other Entities ``` Payment ├── Account (who earned the money) │ └── Payment Terms (frequency, threshold, method) ├── Payee (who receives the money) │ └── Bank Details (account number, routing, SWIFT) ├── Ledger Balance (payable amount determined here) │ ├── Net Revenue (credit side) │ ├── Advances (debit side — must be recouped) │ ├── Reserves (temporarily withheld) │ └── Adjustments (manual credits/debits) ├── Statement Period (which period triggered this payment) ├── Payment Eligibility │ ├── Tax Info (W-9/W-8 on file) │ ├── Payee Setup (bank details valid) │ ├── Payment Holds (none active) │ ├── Threshold (balance ≥ minimum) │ └── Advance Recouped (no unrecouped balance) └── Payment Entity └── Status: Pending → Approved → Disbursed → Completed / Failed ``` --- ## What We Can Look Up Live With an **Account ID**: - Current **payment eligibility** status and ineligibility reason - **Payment terms** — frequency, threshold, method, currency - Active **payment holds** and hold history - **Payable balance** per contract - **Ledger balance** — the real-time financial position With an **Account ID + Statement Period ID**: - **Payment entity status** — whether a payment was created for that period - Payment entity processing state (Pending, Approved, Disbursed, etc.) **Not available** (direct the user elsewhere): - Bank transfer reference numbers and wire confirmations - Full payment disbursement history with dates and amounts - Check delivery tracking --- # Chapter 8: Adjustments — Manual Credits, Debits, and Transfers **Adjustments** are manual financial entries applied to an account's ledger — credits, debits, transfers, and corrections that don't come from normal royalty processing. They are the escape valve for everything the automated royalty engine can't handle. --- ## What Is an Adjustment? A manual change to an account's ledger within a specific statement period: - **Credit** — increases the balance (e.g. underpaid revenue correction) - **Debit** — decreases the balance (e.g. overpayment clawback, fee charge) - **Transfer** — moves money between contracts/accounts (net zero) --- ## Adjustment Types (95 Valid Types) ### Revenue Corrections | Type | Description | |------|-------------| | **Adjustment** | Generic catch-all correction | | **Commission Adjustment** | Fix an incorrect commission rate | | **Override Royalty** | Manually override a calculated royalty | | **Override Share of Costs** | Correct cost allocation | | **Out of Period Payment** | Revenue belonging to a past period | | **Retroactive Performance Royalty Payment** | Backdated performance royalty | ### Advances & Recoupment | Type | Description | |------|-------------| | **Advance (Draw-Down)** | New advance disbursement | | **Advance Recoupment** | Manual recoupment outside normal processing | | **Cross Recoupment** | Manual cross-contract recoupment | | **Label Advance** | Label-level advance | | **Publisher Advance** | Publishing-level advance | | **Non-Recoupable Advance Credit** | Advance that doesn't need to be earned back | | **Non-Recoupable Bonus** | Bonus with no recoupment requirement | ### Transfers & Settlements | Type | Description | |------|-------------| | **Transfer** | Move money between contracts on same account | | **Transfer of Income** | Move earned revenue to another contract/account | | **Balance Transfer** | Move entire balance between accounts | | **Balance Roll Forward** | Carry balance to next period | | **Settlement** | Legal or business settlement lump sum | ### Fees & Costs | Type | Description | |------|-------------| | **Admin Fees** | Administrative charges | | **Bank Fees / Wire Fee / Check Fee** | Transfer and disbursement fees | | **Legal Fees** | Legal costs charged to account | | **Marketing Fund / Marketing Fund (Draw-down)** | Marketing costs/drawdowns | | **Registration Fee / Release Maintenance Fee / Membership Fees** | Platform charges | ### Physical Distribution | Type | Description | |------|-------------| | **Physical Manufacturing / Freight / Storage / Receiving** | Production and logistics costs | | **Physical Marketing / Coop / Publicity** | Marketing for physical releases | | **Physical Reserves Withheld / Released** | Physical return reserves | | **Physical Returns Processing / Rework / Scrap** | Returns and inventory handling | | **Physical Net Receipts Monthly Balance / Physical Other** | Misc. physical costs | ### Tax-Related | Type | Description | |------|-------------| | **Domestic W9 Withholding** | U.S. domestic tax withholding | | **Foreign Withholding** | International tax withholding | | **No U.S. Tax ID Catch Up / Current** | Withholding for missing tax ID | | **Treaty W/H Catch Up / Current / Reversal** | Treaty-rate withholding | | **VAT Tax** | Value-added tax adjustment | ### Flowthrough | Type | Description | |------|-------------| | **Flowthrough** | Revenue flowing through to sub-accounts or payees | > ⚠️ **Apply to Flowthrough Payment** (`Y` or `N`) is always required for Flowthrough type. ### Publishing | Type | Description | |------|-------------| | **Mechanicals / Performance Royalties / Publisher Earnings** | Publishing royalty adjustments | | **Manual / System Release of Publishing Escrow** | Escrow releases | | **Offset to Pub Admin release from Accrual** | Admin accrual offset | | **Reversal of Publishing** | Prior publishing adjustment correction | ### Other Notable Types | Type | Description | |------|-------------| | **Black Box** | Unallocated revenue redistribution | | **Bonus Credit** | Discretionary bonus | | **Brand Partnership / Sync License / Master License** | Licensing revenue | | **Breakage / Escheat Payments** | Unredeemed credits / unclaimed funds | | **Collaborator Revenue / Tax Allocation** | Splitting revenue or tax among collaborators | | **Direct Ad Sales / Spotify Payment / Podcast** | Platform-specific revenue | | **Forced Zero Out Balance / Garnishment** | Balance cleanup / court orders | | **IODA / IRIS Label Earnings Adj.** | Platform-specific earnings corrections | | **Label Earnings / Expenditure / Publisher Costs** | Label-level adjustments | | **Orchard Profit Share** | The Orchard profit distribution | | **Payment Failure / Returned Check / Stale Dated Check** | Failed payment reversals | | **Reclass Between Labels** | Revenue reclassification | | **Recoupable Facebook ADS / Film Cost / Interactive Marketing** | Recoupable marketing costs | | **Reversal of Check Fee / Encoding Fees** | Fee refunds | | **SAG Residuals / Shared Costs / Compilations** | Residuals and cost splits | | **Balance Payment / Monthly Royalty Payment** | Manual payment triggers | | **Distribution - Other / Theatrical** | Non-standard distribution revenue | --- ## Adjustment Fields | Field | Required | Description | |-------|:--------:|-------------| | **Account ID** | ✅ | Account to adjust | | **Contract ID** | ✅ | Contract within the account | | **Adjustment Type** | ✅ | One of the 95 valid types | | **Amount** | ✅ | Positive = credit, negative = debit | | **Currency** | ✅ | One of 56 supported currency codes | | **Activity Month/Year** | ✅ | When the revenue event originally happened | | **Statement Month/Year** | ✅ | Which period to apply the adjustment to | | **Distribution Type** | Conditional | `Digital` or `Physical` — required with a UPC | | **UPC** | Optional | Product/release identifier | | **ISRC** | Optional | Track/recording identifier | | **Apply to Flowthrough Payment** | Conditional | `Y` or `N` — required for Flowthrough type | | **Client Facing Comments** | Optional | Visible to account holder (max 180 chars) | | **Internal Note** | Optional | Internal only (max 180 chars) | --- ## Activity Month vs. Statement Month | | Meaning | |---|---| | **Activity Month/Year** | When the revenue event *actually happened* | | **Statement Month/Year** | Which accounting period it's *applied to* | These match for current-period adjustments and differ for retroactive corrections. When intent is unclear, always confirm both with the user. --- ## Submission Paths ### Path 1: File Upload Download template → Fill rows → Validate → Select period → Confirm → Upload → Airflow processes → Batch ID returned ### Path 2: Generated Adjustments Describe scenario → System gathers data → Calculates rows with workings → Review preview → Confirm → Submit → Batch ID returned > **Never submit without explicit user confirmation.** --- ## Validation - **File-level:** correct format, all required columns present - **Row-level:** valid Account/Contract IDs, valid type/currency/amounts, date ranges, field rules - **Airflow (post-submit):** eligibility, balance sufficiency, duplicate detection --- ## Calculation Patterns ### Transfer of Income ``` Contract A net revenue: $100,000 — Transfer 30% to Contract B Row 1 (Debit): Contract A −$30,000 Row 2 (Credit): Contract B +$30,000 Net: $0 ← always zero-sum ``` ### Flowthrough Distribution ``` Total: $50,000 — Split by store revenue share Row 1: Spotify +$30,000 (60%) Apply to Flowthrough: Y Row 2: Apple Music +$12,500 (25%) Apply to Flowthrough: Y Row 3: Amazon +$7,500 (15%) Apply to Flowthrough: Y ``` ### Direct Amount ``` "Credit $5,000 to Account 12345, Contract 6789, March 2024" Row 1: Account 12345 / Contract 6789 +$5,000 Type: Adjustment | Activity: Mar 2024 | Statement: current open period ``` --- ## Adjustment Batches | Field | Description | |-------|-------------| | **Batch ID** | Unique identifier for the group of rows submitted together | | **Status** | Pending → Processing → Applied / Failed | | **Deep Link** | `{FRONTEND_ROYALTIES_URL}/adjustments/{batchId}` | Airflow validation takes minutes. Status can be checked at any time via the batch ID. --- ## Ambiguity Rules | Situation | Resolution | |-----------|------------| | Multiple open periods | List them, ask which to target | | Contract name not unique | Show matches with IDs, ask to confirm | | Zero revenue for period | Flag it, ask if period is correct | | Retroactive vs. current | Ask for both activity and statement dates | | Net vs. gross revenue | Confirm which the user means | | Flowthrough type, no Y/N | Always ask before submitting | --- ## Key Concepts | Concept | Plain English | |---------|---------------| | **Credit** | Increases the account balance | | **Debit** | Decreases the account balance | | **Transfer** | Moves money — net zero across rows | | **Activity Month** | When revenue happened in the real world | | **Statement Month** | Which period the adjustment books to | | **Flowthrough** | Pass-through payment — requires Y/N flag | | **Batch** | A group of adjustment rows submitted together | | **Airflow** | The post-submit validation and processing engine | --- # Chapter 9: Products & Catalog — ISRCs, UPCs, and the Music Itself **Products** are the music — the tracks, albums, and releases that generate all the revenue flowing through Abacus. While most of the system focuses on money (contracts, balances, payments), products are the *source* of that money. Understanding how Abacus identifies, tracks, and links music to accounts and royalties is essential. --- ## What Is a Product? In Abacus, a **Product** is a releasable unit of music — a track, an album, a single, an EP, or a compilation. Every product has unique identifiers that link it to: - The **account** that owns or distributes it - The **revenue** it generates on DSPs - The **contract** that governs its royalty rate - The **artist** who recorded it Products are the bridge between the music industry (recordings, releases) and the financial system (royalties, payments). --- ## Product Identifiers Every product in Abacus is identified by one or more industry-standard codes: ### ISRC — International Standard Recording Code The **ISRC** is the unique identifier for a **single recording** (a track). | Field | Value | |------------|--------------------------| | **Format** | CC-XXX-YY-NNNNN | | **Example**| US-S1Z-99-00001 | | **Length** | 12 characters | | **Scope** | Identifies one recording | Breaking down the format: ``` US - S1Z - 99 - 00001 │ │ │ │ │ │ │ └── 5-digit sequence number │ │ └── 2-digit year of reference │ └── 3-character registrant code (label/distributor) └── 2-character country code ``` **ISRC is track-level.** One album of 12 tracks has 12 ISRCs — one per recording. > Always display ISRCs in dashed format: `US-S1Z-99-00001` > Accept any format (with or without dashes) — the system handles normalization. ### UPC / EAN — Universal Product Code / European Article Number The **UPC** (or EAN) is the unique identifier for a **release** (an album, EP, or single as a product for sale). | Field | Value | |------------|------------------------------| | **Format** | 12-digit (UPC) or 13-digit (EAN) numeric string | | **Example**| 888003244085 | | **Scope** | Identifies one release/product | **UPC is release-level.** One album has one UPC, but contains many tracks each with their own ISRC. ``` Album: "Midnight Sessions" (UPC: 888003244085) ├── Track 1: "Neon Lights" (ISRC: US-S1Z-23-00001) ├── Track 2: "Fading Out" (ISRC: US-S1Z-23-00002) ├── Track 3: "Stay With Me" (ISRC: US-S1Z-23-00003) └── Track 4: "Golden Hour" (ISRC: US-S1Z-23-00004) ``` --- ## ISRC vs. UPC — When to Use Which | Question | Use | |---------------------------------------------|----------| | "Which account owns this track?" | ISRC | | "Which account owns this album?" | UPC | | "What royalties did this recording earn?" | ISRC | | "What are the release details for this LP?" | UPC | | "Who distributes this album?" | UPC | | "What label is this recording on?" | ISRC | ### Resolution Paths **ISRC → Account:** ``` ISRC provided │ ▼ Look up product(s) by ISRC │ (may return multiple products if re-released) ▼ Get vendor_id from product │ (vendor_id = account_id in Abacus) ▼ Look up account details ``` **UPC → Account:** ``` UPC provided │ ▼ Look up product by UPC │ (one product per UPC) ▼ Get vendor_id from product │ ▼ Look up account details ``` > A single ISRC may return **multiple products** if the same recording appears on > multiple releases (e.g. an original album + a greatest hits compilation). When this > happens, present all matching products and their details — never silently pick one. --- ## Product Fields | Field | Description | |------------------------|------------------------------------------------------------------| | **Product ID** | Abacus internal numeric identifier | | **Product Name** | The release title (e.g. "Midnight Sessions") | | **Artist Name** | The credited artist(s) on the release | | **UPC** | Universal Product Code for the release | | **ISRC** | International Standard Recording Code (track-level) | | **Vendor ID** | The account ID of the distributor/label — links product to account| | **Label** | The record label the release is signed to | | **Release Date** | Official release date | | **Product Type** | Album, Single, EP, Compilation, etc. | | **Configuration** | Digital, CD, Vinyl, Cassette, etc. | | **Status** | Active, Inactive, Takedown, etc. | --- ## How Products Link to Royalties Products are the entry point for revenue matching. When a DSP reports revenue, it includes identifiers (ISRC, UPC) that Abacus uses to match the revenue to the correct account and contract: ``` DSP Revenue Report: ISRC: US-S1Z-23-00001 Store: Spotify Territory: US Transaction Type: ADA Revenue: $1,250.00 │ ▼ Abacus Matches ISRC → Product → Vendor (Account) │ ▼ Account's Contract Terms Applied (e.g. 80% net rate for ADA streams) │ ▼ Net Revenue Credited to Account Ledger: $1,000.00 Commission Retained by Sony: $250.00 ``` --- ## Product Configurations The same recording can exist in multiple **configurations** — different formats that may carry different royalty rates under a contract: | Configuration | Description | |-----------------|--------------------------------------------------| | **Digital** | Streaming and download files | | **CD** | Compact disc physical release | | **Vinyl** | LP or 7" record | | **Cassette** | Cassette tape release | | **DVD/Blu-ray** | Video release | Contract conditions may specify different rates for digital vs. physical configurations — for example, an 80% digital rate and a 70% physical rate for the same recording. --- ## Product Status Products move through lifecycle states that affect distribution and royalty eligibility: | Status | Meaning | |-----------------|-----------------------------------------------------------------| | **Active** | Product is live — available on DSPs, generating revenue | | **Inactive** | Product exists but is not actively distributed | | **Takedown** | Product has been removed from DSPs — no new revenue | | **Pending** | Product is being set up / awaiting delivery to DSPs | > A product in **Takedown** status will no longer generate new streaming revenue, > but historical revenue already reported by DSPs is still processed normally. --- ## Multiple Products per ISRC One ISRC can appear on multiple products (releases). This is common when: - A track appears on the **original album** AND a **greatest hits** compilation - A recording is **re-released** on a new label or under a new UPC - A track is included in a **bundle** or **box set** ``` ISRC: US-S1Z-23-00001 ("Neon Lights") appears on: Product 1: "Midnight Sessions" (UPC: 888003244085) Vendor: Account 12345 (Original Label) Release Date: 2023-03-15 Product 2: "Greatest Hits 2024" (UPC: 888009876543) Vendor: Account 12345 (Same Label) Release Date: 2024-01-01 Product 3: "Now That's What I Call Music Vol. 90" (UPC: 888001122334) Vendor: Account 67890 (Compilation Label) Release Date: 2023-11-01 ``` > When multiple products are returned for an ISRC, present **all of them** with > their product names, UPCs, and vendor IDs. Never silently pick just the first result. --- ## Products and Accounts The link between a product and an account runs through the **vendor_id** field: ``` Product.vendor_id = Account.account_id ``` This means: - Every product belongs to exactly one account (its distributor/vendor) - An account can have many products (its entire catalog) - Looking up a product by ISRC or UPC gives you the account that owns it - The account's contracts then determine the royalty rate for that product's revenue --- ## Products and Contracts Products don't directly reference contracts — the link is through the **account**: ``` Product (ISRC / UPC) │ └── vendor_id → Account │ └── Contract(s) │ └── Terms & Conditions │ └── Royalty Rate Applied to Revenue ``` However, some contracts may include **product-level exclusions** or **track-level terms** that apply specific rates to individual ISRCs or UPCs rather than the whole catalog. --- ## Distribution Type When revenue is associated with a product, it carries a **Distribution Type** flag: | Distribution Type | Description | |-------------------|---------------------------------------------------| | **Digital** | Revenue from streaming, downloads, digital sales | | **Physical** | Revenue from CD, vinyl, or other physical sales | This flag matters for adjustments — when a UPC is provided on an adjustment row, the Distribution Type must be specified as `Digital` or `Physical`. --- ## Products in the Adjustment Context When submitting adjustments, product identifiers can be included to tie the adjustment to a specific release or recording: | Field | When to Use | |---------------------|---------------------------------------------------------| | **UPC** | Adjustment relates to a specific album/release | | **ISRC** | Adjustment relates to a specific track/recording | | **Distribution Type** | Required when a UPC is provided (`Digital` or `Physical`) | Including ISRCs and UPCs on adjustments provides a clearer audit trail — it shows exactly which product the correction relates to. --- ## Key Concepts to Remember | Concept | Plain English | |--------------------------|------------------------------------------------------------------------------| | **Product** | A releasable unit of music — track, album, EP, single, or compilation | | **ISRC** | Track-level identifier — one per recording (CC-XXX-YY-NNNNN) | | **UPC** | Release-level identifier — one per album/product | | **Vendor ID** | The account ID of the label/distributor — links the product to the account | | **Multiple ISRCs per UPC** | An album has many tracks, each with its own ISRC | | **Multiple Products per ISRC** | A track can appear on multiple releases — always show all matches | | **Configuration** | The format of the release: digital, CD, vinyl, etc. | | **Distribution Type** | Digital or Physical — determines which revenue stream and rate applies | | **Takedown** | Product removed from DSPs — no new revenue, but history is preserved | --- ## How Products Connect to Other Entities ``` Product (ISRC / UPC) ├── Account (via vendor_id) │ ├── Contracts → Royalty Rates │ └── Ledger → Balance & Payments ├── Revenue Events │ ├── Store (which DSP reported it) │ ├── Territory (where the stream happened) │ └── Transaction Type (what kind of consumption) ├── Statement Period (when the revenue was booked) └── Adjustments ├── UPC-level (release-specific corrections) └── ISRC-level (track-specific corrections) ``` --- ## What We Can Look Up Live With an **ISRC**: - All products that contain this recording - The vendor (account) that owns each product - Product name, UPC, label, release date, and status With a **UPC**: - The specific product/release - The vendor (account) that distributes it - Full product details including label, artist, release date, and configuration With a **Product ID**: - Full product details - Associated account (vendor_id) - Release metadata With an **Account ID**: - Revenue breakdown — which products/stores are earning for this account - Use Snowflake for catalog-wide analytics (top tracks, best performing releases) --- # Chapter 10: Tax & Payee Setup — The Last Mile Before Payment Before a single dollar leaves Abacus, two non-negotiable requirements must be satisfied: the account must have valid **tax documentation** on file, and a **payee** must be configured with working bank details. These are the last mile of the payment pipeline — without them, no payment is ever created, regardless of how much the account has earned. --- ## Why Tax & Payee Setup Matters Abacus will accumulate a balance indefinitely for an account that hasn't completed setup. The money is there — it just can't move. Both conditions must be true simultaneously: ``` Valid Tax Info ✅ + Valid Payee ✅ = Payment Eligible ``` Miss either one and the account is blocked, the balance rolls forward, and nothing is disbursed until the issue is resolved. --- ## Tax Documentation ### Why It's Required Sony Music is legally required to collect tax identification information from all payees before making royalty payments. This applies to: - **U.S. entities** — must file a W-9 (Tax ID / EIN / SSN) - **Foreign entities** — must file a W-8 series form (W-8BEN, W-8BEN-E, W-8ECI, etc.) Without valid tax documentation, Abacus places an automatic **Tax Hold** on the account, blocking all payments. ### U.S. Tax Forms | Form | Who Uses It | |------------|----------------------------------------------------------| | **W-9** | U.S. individuals and entities (provides TIN/EIN/SSN) | ### Foreign Tax Forms | Form | Who Uses It | |---------------|----------------------------------------------------------| | **W-8BEN** | Foreign individuals claiming treaty benefits | | **W-8BEN-E** | Foreign entities claiming treaty benefits | | **W-8ECI** | Foreign entities with income effectively connected to U.S. trade | | **W-8IMY** | Intermediaries and flow-through entities | | **W-8EXP** | Foreign governments and tax-exempt organizations | ### Tax Hold Triggers A Tax Hold is automatically placed when: - No tax form has ever been submitted - A submitted tax form has **expired** (W-8 forms expire after 3 years) - The tax form was submitted but **rejected** (invalid TIN, mismatched name, etc.) - The account's status changes in a way that requires a new form ### Tax Withholding When tax documentation is missing or incomplete, Abacus may apply **withholding** rather than blocking payment entirely — depending on the account's configuration: | Situation | Withholding Applied | |------------------------------------|-----------------------------------------------| | **No U.S. Tax ID (current)** | 28% backup withholding on U.S. earnings | | **No U.S. Tax ID (catch up)** | Retroactive withholding for prior periods | | **Foreign entity, no treaty** | 30% withholding on U.S.-source income | | **Foreign entity, treaty applies** | Reduced rate per applicable tax treaty | | **Treaty W/H Reversal** | Correction of over-withheld treaty amounts | These withholding scenarios are handled as **adjustment types** in Abacus (see Chapter 8). --- ## Tax Info Fields | Field | Description | |-------------------------|----------------------------------------------------------| | **Tax Form Type** | W-9, W-8BEN, W-8BEN-E, W-8ECI, etc. | | **Tax ID (TIN/EIN/SSN)**| The taxpayer identification number | | **Entity Name** | Name as it appears on the tax form | | **Status** | Valid, Expired, Pending Review, Rejected | | **Submission Date** | When the form was submitted | | **Expiry Date** | When the form expires (W-8 forms: 3 years) | | **Country** | Country of tax residency | --- ## Payee Setup ### What Is a Payee? A **payee** is the entity that physically receives the payment — the person or organization whose bank account the money is wired to. The payee may be: - The **account holder** themselves (most common) - A **management company** receiving on behalf of the artist - A **publisher or administrator** collecting on behalf of the rights holder - A **holding company** or legal entity One account can have multiple payees (e.g. for different contracts or revenue types), but only one can be the **primary active payee** at any time. ### Payee Fields | Field | Description | |------------------------|----------------------------------------------------------| | **Payee ID** | Unique numeric identifier | | **Payee Name** | Legal name of the receiving entity | | **Payee Type** | Individual, Company, Publisher, etc. | | **Status** | Active, Inactive, Pending | | **Payment Method** | Wire, ACH, Check | | **Bank Account Number**| Destination bank account | | **Routing Number** | U.S. ACH routing number | | **SWIFT / BIC Code** | International wire identifier | | **IBAN** | International bank account number (Europe) | | **Bank Name** | Name of the receiving bank | | **Bank Country** | Country where the bank is located | | **Currency** | Currency of disbursement | ### Payee Hold A **Payee Hold** is triggered automatically when: - No payee has been configured - Bank details are missing or incomplete - A wire transfer was rejected (invalid account number, closed account) - Bank details have changed and are pending re-verification ### Payee History Every change to payee details is tracked in an **audit trail**: ``` 2023-01-10: Payee created — Wire / Chase Bank / USD 2023-06-15: Bank account updated (new account number) 2024-02-01: Payment failure — wire rejected 2024-02-05: Bank details corrected 2024-02-06: Payee Hold removed ``` --- ## Tax & Payee Together — Eligibility Flow ``` Payment Evaluation Begins │ ├── Tax Hold Active? │ YES → Block payment, roll forward balance │ NO → Continue │ ├── Payee Configured? │ NO → Block payment, roll forward balance │ YES → Continue │ ├── Payee Hold Active? │ YES → Block payment, roll forward balance │ NO → Continue │ ├── Balance ≥ Threshold? │ NO → Roll forward │ YES → Continue │ └── Advance Fully Recouped? NO → Roll forward YES → Payment Created ✅ ``` --- ## Change History Both tax and payee configurations maintain a **change history** — a timestamped record of every modification, who made it, and what changed. This supports: - **Audits** — proving when documentation was on file - **Dispute resolution** — tracing why a payment was blocked - **Compliance** — demonstrating due diligence in tax collection --- ## Key Concepts to Remember | Concept | Plain English | |---------|---------------| | **Tax Hold** | Payment blocked due to missing/expired/invalid tax documentation | | **W-9** | Required form for U.S. entities | | **W-8 (series)** | Required form for foreign entities — expires every 3 years | | **Withholding** | Tax deducted from payment when documentation is incomplete | | **Payee** | The entity whose bank account receives the payment | | **Payee Hold** | Payment blocked due to missing or invalid bank details | | **Primary Payee** | The active payee designated to receive disbursements | | **Payee History** | Audit trail of all payee configuration changes | | **Both Required** | Tax info AND payee setup must both be valid for payment to occur | --- ## What We Can Look Up Live With an **Account ID**: - Current tax form status (type, expiry, valid/expired/rejected) - Active payee and payment method - Tax holds and payee holds (active and history) - Full payee change history - Full tax info change history - Payment eligibility status and ineligibility reason --- # Chapter 1b: Accounts & Payees — Who Gets Paid The **Account** is the central organizing unit of Abacus. Every contract, every dollar of revenue, every advance, every payment — all of it rolls up to an account. Understanding what an account is, how it's structured, and how payees connect to it is fundamental to navigating the entire platform. --- ## What Is an Account? An account is the **top-level financial entity** in Abacus. It represents a business relationship between Sony Music and an artist, label, distributor, or other rights holder. Every account: - Has a unique **Account ID** (numeric) - Owns one or more **contracts** (the deals) - Accumulates **revenue** from DSPs - Maintains a **ledger balance** (money owed or unrecouped) - Has one or more **payees** (who receives payments) - Has **payment terms** (when and how payments are made) - Has **tax documentation** on file (required for payment) --- ## Account Types Accounts come in several types depending on the nature of the relationship: | Account Type | Description | |------------------|-------------------------------------------------------------------| | **Artist** | An individual recording artist | | **Label** | A record label distributing through Sony | | **Distributor** | A distribution company or aggregator | | **Publisher** | A music publisher collecting royalties | | **Compilation** | An account specific to compilation releases | | **Joint Venture**| A shared deal between Sony and a partner | --- ## Account Fields | Field | Description | |-------------------------|---------------------------------------------------------------| | **Account ID** | Unique numeric identifier — the primary key in Abacus | | **Account Name** | The name of the artist, label, or entity | | **Account Type** | Artist, Label, Distributor, Publisher, etc. | | **Status** | Active, Inactive, Closed | | **Payment Terms** | Frequency, threshold, method, and currency | | **Payee Currency** | The currency all earnings are reported and paid in | | **Tax Info** | Form type, status, expiry — required for payment | | **Agreement Type** | The category of deal (e.g. Distribution, License, JV) | | **Associated Contracts**| All contracts linked to this account | --- ## Account Status | Status | Meaning | |--------------|--------------------------------------------------------------------| | **Active** | Account is live — revenue flows in, payments go out | | **Inactive** | Account exists but is not actively processing | | **Closed** | Account is terminated — no new activity, balance may still exist | > A closed account may still have an outstanding balance or unrecouped advance. > The ledger remains intact even after closure until the balance is resolved. --- ## Account Hierarchy Some accounts exist within a hierarchy — a parent/child relationship between a label account and its artist sub-accounts: ``` Parent Account: Big Label Group (Account 1000) ├── Artist Account: Artist A (Account 1001) ├── Artist Account: Artist B (Account 1002) └── Artist Account: Artist C (Account 1003) ``` In this structure: - Each **artist account** has its own contracts, ledger, and payee - The **parent label account** may aggregate revenue or share costs - **Cross-recoupment** may be configured across sibling accounts - **Flowthrough adjustments** may distribute label-level revenue down to artist accounts --- ## Payment Terms Every account has a **Payment Terms** configuration that governs disbursement: | Field | Description | |------------------------|-------------------------------------------------------------| | **Payment Frequency** | Monthly, Quarterly, Semi-Annual, Annual | | **Payment Threshold** | Minimum balance to trigger a payment (e.g. $100) | | **Payment Method** | Wire Transfer, ACH, Check | | **Payment Currency** | Currency of disbursement (matches payee currency) | | **Payment Delay** | Optional delay after period close before payment is released| --- ## Agreement Types The **Agreement Type** describes the category of deal the account operates under: | Agreement Type | Description | |--------------------|----------------------------------------------------------------| | **Distribution** | Sony distributes the account's music for a commission | | **License** | Sony licenses content from the account for a fee | | **Joint Venture** | Shared ownership and revenue split between Sony and the account| | **Service** | Sony provides services (marketing, etc.) for a fee | | **Publishing** | Sony administers publishing rights for the account | The agreement type shapes the contract structure and royalty rates (see Chapter 12). --- ## What Is a Payee? A **payee** is the entity that physically receives the money when a payment is disbursed. It is linked to an account and carries the bank details. The payee and the account are **not always the same entity**: ``` Account: "The Smith Band" (the artist) Payee: "Smith Band Management LLC" (their management company) → Bank: First National Bank, Account #123456789 ``` ### Payee Fields | Field | Description | |---------------------|--------------------------------------------------------------| | **Payee ID** | Unique numeric identifier | | **Payee Name** | Legal name of the receiving entity | | **Payee Type** | Individual, Company, Publisher, etc. | | **Status** | Active, Inactive, Pending | | **Payment Method** | Wire, ACH, Check | | **Bank Details** | Account number, routing, SWIFT/BIC, IBAN, bank name/country | | **Currency** | Currency of disbursement | --- ## One Account, Multiple Payees An account can have more than one payee configured — for example: - Different payees for different **contracts** (one for label deal, one for publishing) - A historical payee (now inactive) replaced by a new one - A backup payee for a specific territory or currency Only one payee can be **active** at any given time for a given payment context. --- ## Payee History & Audit Trail Every change to payee details is recorded with a timestamp and the user who made the change. This supports compliance, audits, and dispute resolution: ``` 2022-05-01: Payee created — ACH / Wells Fargo / USD 2023-03-12: Payment method changed to Wire 2023-08-20: Bank account number updated 2024-01-05: Payment failure — wire rejected (account closed) 2024-01-08: New bank details submitted 2024-01-09: Payee Hold removed — payment eligible ``` --- ## Account Activity Summary An account's **activity summary** provides a high-level financial snapshot: | Field | Description | |---------------------------|-------------------------------------------------------| | **Total Gross Revenue** | All revenue earned before commission | | **Total Net Revenue** | Revenue after commission — the account's share | | **Total Advances** | Sum of all advances issued | | **Total Recouped** | Advances earned back so far | | **Unrecouped Balance** | Remaining advance to be earned back | | **Total Payments Made** | All payments disbursed to date | | **Current Balance** | Real-time ledger position | | **Payable Balance** | Amount eligible for disbursement right now | --- ## How Accounts Connect to Everything Else ``` Account ├── Contracts (the deals — terms, rates, advances) │ └── Contract Terms → Royalty Rates by Store / Territory / Transaction Type ├── Revenue (money earned from DSPs) │ └── Statement Periods → Per-period earnings breakdown ├── Ledger Balance │ ├── Net Revenue (credit) │ ├── Advances (debit — must be recouped) │ ├── Adjustments (manual credits/debits) │ └── Payments Made (debit — disbursed funds) ├── Payee(s) │ ├── Bank Details → Where money is sent │ └── Payee History → Audit trail of changes ├── Tax Documentation │ ├── W-9 (U.S.) or W-8 (Foreign) │ └── Tax Hold if missing/expired ├── Payment Terms │ ├── Frequency, Threshold, Method, Currency │ └── Determines when and how payments are created └── Payment Eligibility ├── Tax Info ✓ ├── Payee Setup ✓ ├── No Holds ✓ ├── Threshold Met ✓ └── Advance Recouped ✓ ``` --- ## Key Concepts to Remember | Concept | Plain English | |---------|---------------| | **Account** | The top-level entity — every deal, dollar, and payment belongs here | | **Account ID** | The unique numeric key — always needed to look anything up | | **Payee** | Who receives the money — may differ from the account holder | | **Primary Payee** | The active payee currently designated for disbursement | | **Payee History** | Full audit trail of every bank detail change | | **Payment Terms** | Rules for when and how the account is paid | | **Agreement Type** | The category of deal: Distribution, License, JV, etc. | | **Activity Summary** | High-level financial snapshot of the account's lifetime position | | **Account Hierarchy** | Parent/child structure for label + artist relationships | --- ## What We Can Look Up Live With an **Account ID**: - Full account details (name, type, status, agreement type) - Payment terms (frequency, threshold, method, currency) - Tax documentation status and history - Active payee and payment method - Payee history (all changes with timestamps) - Payment holds (active and history) - Payment eligibility status and reason - Activity summary (lifetime revenue, advances, payments, balance) - All associated contracts With an **Account Name** (partial or full): - Search returns matching accounts with their IDs - Use the ID from search results for all follow-up queries --- # Chapter 11: Publishing & Sync — Rights, Royalties, and Licensing Recording royalties are only half the story. Every song has two distinct layers of rights — the **master recording** and the **underlying composition** — and each generates its own royalties through its own pipeline. Understanding how publishing and sync licensing fit into Abacus, and where they connect to the broader royalty flow, is essential for anyone working with songwriters, publishers, or licensing deals. --- ## Two Layers of Every Song ``` "Neon Lights" — a song played on Spotify Layer 1: The Master Recording Who owns it: The record label (or artist, if self-released) What it earns: Master royalties — covered throughout this guide Paid by: DSPs (Spotify, Apple Music, etc.) to Sony / the label Layer 2: The Underlying Composition (Publishing) Who owns it: The songwriter(s) and their publisher(s) What it earns: Publishing royalties — mechanical + performance Paid by: DSPs and collection societies to the publisher ``` These two layers are **legally and financially independent**. The same song can have different owners for each layer — and often does. --- ## Publishing Royalty Types ### Mechanical Royalties **Mechanicals** are paid for the reproduction of a composition — every time a song is streamed, downloaded, or physically manufactured. | Context | Description | |---------|-------------| | **Digital Mechanicals** | Paid per stream or download by DSPs | | **Physical Mechanicals** | Paid per unit manufactured (CD, vinyl) | | **Statutory Rate** | Set by law in the U.S. (Copyright Royalty Board) | | **Negotiated Rate** | Agreed rate that differs from statutory | In the U.S., mechanical royalties for streams are currently calculated as the greater of a per-stream rate or a percentage of revenue — governed by the **Phonorecords rate** set by the Copyright Royalty Board (CRB). ### Performance Royalties **Performance royalties** are paid when a composition is publicly performed — broadcast on radio, streamed, or played in a public venue. | Source | Collected By | |--------|-------------| | **Radio broadcast** | ASCAP, BMI, SESAC (U.S.) | | **Streaming (public performance)** | PROs collect from DSPs | | **TV / Film broadcast** | PROs and sync licenses | | **Live performance** | PROs collect from venues | Performance royalties flow through **Performing Rights Organizations (PROs)**, not directly through Abacus. Abacus may receive PRO distributions as an inbound payment and apply them to the correct account via adjustment. ### Synchronization (Sync) Royalties **Sync royalties** are paid when a composition (and usually the master recording) is licensed for use alongside visual media: | Use Case | Description | |----------|-------------| | **Film** | Song placed in a movie scene or trailer | | **TV** | Song placed in a TV show, commercial, or promo | | **Video Game** | Song licensed for in-game use | | **Online Video** | Song used in a YouTube video, ad, or social content | | **Brand / Ad** | Song licensed for a brand campaign | Sync deals are **negotiated individually** — there is no statutory rate. The fee is whatever the licensor and licensee agree to. --- ## The Publishing Rights Stack A single composition can have multiple rights holders: ``` Song: "Neon Lights" Written by: Artist A (50%) + Songwriter B (50%) Artist A's share: └── Administered by: Sony Music Publishing └── Writer share: 50% of writer's net publisher share (NPS) └── Publisher share: 50% of publisher's NPS Songwriter B's share: └── Administered by: Independent Publisher LLC └── Writer share: 50% of NPS └── Publisher share: 50% of NPS ``` Sony Music Publishing administers rights on behalf of its songwriters — collecting royalties, registering works, and distributing earnings. --- ## Key Publishing Concepts ### Copyright Ownership vs. Administration | Concept | Description | |---------|-------------| | **Copyright Owner** | The songwriter or their heirs — owns the composition permanently (or for the copyright term) | | **Publisher** | The entity that administers the copyright — registers works, collects royalties, issues licenses | | **Co-Publisher** | A joint owner of the publishing copyright | | **Sub-Publisher** | A publisher that administers rights in a specific territory on behalf of the primary publisher | | **Administrator** | Manages collection and licensing without owning the copyright | ### Royalty Split Publishing royalties are traditionally split between the **writer** and the **publisher**: ``` Total Publishing Royalty: $1,000 Standard Split: Writer Share: 50% → $500 to the songwriter Publisher Share: 50% → $500 to the publisher Co-publishing Split (writer co-owns publishing): Writer Share: 50% → $500 to the songwriter Co-Publisher Share: 25% → $250 to the songwriter's company Publisher Share: 25% → $250 to the publisher ``` ### Controlled Composition A **controlled composition** is a song written (fully or partially) by the recording artist. This matters because labels often include a **controlled composition clause** in recording contracts, which: - Caps the mechanical rate paid to the artist-songwriter at a fraction of the statutory rate (commonly 75%) - Limits the total mechanicals payable on an album regardless of track count --- ## Sync Licensing in Abacus ### How Sync Deals Work ``` Film studio wants to use "Neon Lights" in a movie trailer: Step 1: License Request Studio contacts Sony for: (a) Master license — for the recording (b) Sync license — for the composition (via publisher) Step 2: Negotiation Fee negotiated based on: - Duration of use (how long the clip runs) - Placement (trailer vs. background vs. featured) - Territory (worldwide vs. U.S. only) - Media type (theatrical, home video, streaming) - Term (how long the license lasts) Step 3: License Issued Two licenses issued separately: - Master license: Sony Music Entertainment → Studio - Sync license: Sony Music Publishing → Studio Step 4: Fee Collected Master fee: $50,000 → flows to recording artist's account Sync fee: $50,000 → flows to songwriter's publishing account ``` ### Sync Revenue in Abacus Sync revenue arrives as a lump sum payment and is posted to the account via: - **Adjustment type: Sync License** — for manual application of a sync fee - **Transaction type: SYN** — when sync revenue flows through automated processing ``` Sync License Adjustment: Account: 12345 (Artist Account) Contract: Contract A Adjustment Type: Sync License Amount: +$50,000.00 Activity Month: March 2024 Statement Month: March 2024 Note: "Master sync fee — Paramount trailer license" ``` --- ## Publishing Registration Before royalties can flow, a composition must be **registered** with the relevant societies and databases: | Registry | Description | |----------|-------------| | **PRO (ASCAP / BMI / SESAC)** | Performing rights — radio, streaming performance | | **MLC (Mechanical Licensing Collective)** | U.S. digital mechanical royalties | | **CMRRA** | Canadian mechanical rights | | **MCPS** | UK mechanical rights | | **CISAC / ICE** | International cross-society royalty exchange | | **ISRC** | Identifies the recording (master) | | **ISWC** | Identifies the composition (publishing) | ### ISRC vs. ISWC | Identifier | What It Identifies | Who Issues It | |------------|-------------------|---------------| | **ISRC** | The master recording | Record label / distributor | | **ISWC** | The underlying composition | Publisher / PRO | One composition (one ISWC) can have many recordings (many ISRCs): ``` Composition: "Neon Lights" (ISWC: T-123.456.789-0) └── Original recording: ISRC US-S1Z-23-00001 └── Live version: ISRC US-S1Z-24-00045 └── Acoustic version: ISRC US-S1Z-24-00089 └── Cover by another artist: ISRC US-XYZ-24-00201 (different master, same composition) ``` --- ## Black Box Royalties **Black box** royalties are unclaimed or unmatched publishing royalties — money that has been collected by a society but cannot be attributed to a specific rights holder because: - The composition wasn't registered - The metadata was incomplete or incorrect - The ownership split was disputed or unresolved In Abacus, black box distributions appear as the **Black Box** adjustment type — a redistribution of unclaimed funds to eligible rights holders based on market share or other criteria. ``` Adjustment Type: Black Box Account: 12345 Amount: +$2,340.00 Note: "ASCAP black box distribution Q1 2024" ``` --- ## How Publishing Connects to Abacus Publishing royalties touch Abacus in three ways: ### 1. Inbound as Revenue When Sony Music Publishing collects mechanical royalties from DSPs, those earnings flow into Abacus as revenue attributed to the songwriter's account — processed like any other digital revenue (Chapter 4). ### 2. Inbound as Adjustments PRO distributions (performance royalties), sync fees, and black box distributions that arrive as lump sums are posted via manual adjustments (Chapter 8) using the appropriate adjustment type: | Scenario | Adjustment Type | |----------|----------------| | Sync license fee | Sync License | | Performance royalty distribution | Performance Royalties | | Mechanical royalty correction | Mechanicals | | Black box distribution | Black Box | | Publisher advance | Publisher Advance | | Publisher earnings | Publisher Earnings | | Publishing escrow release | Manual/System Release of Publishing Escrow | | Publishing reversal | Reversal of Publishing | | Pub admin release from accrual | Offset to Pub Admin release from Accrual | ### 3. Via GraphQL (Cross-Team Data) Publishing rights, ISWC registrations, ownership splits, and co-publisher relationships live in the publishing service — accessible via GraphQL (Chapter 13), not the financial REST APIs. ``` graphql_explore_skill(search_term: "publishing rights") → Returns: publishingRights / ownershipSplits / iswc / writerShare ``` --- ## Sync vs. Other Revenue Types — At a Glance | Revenue Type | Source | Rate | Basis | Abacus Path | |-------------|--------|------|-------|-------------| | **Streaming (ADA/AEA)** | DSP monthly report | Contract rate | Per stream | Automated | | **Download (DPD)** | DSP monthly report | Contract rate | Per unit | Automated | | **Physical (PHY)** | Distribution report | Contract rate | Per unit | Automated | | **Performance (PRO)** | Quarterly PRO distribution | Varies | Negotiated | Adjustment | | **Mechanical** | MLC / CMRRA / MCPS | Statutory/negotiated | Per stream or unit | Revenue or Adjustment | | **Sync (Master)** | One-time license fee | Negotiated | Per placement | Adjustment | | **Sync (Publishing)** | One-time license fee | Negotiated | Per placement | Adjustment | --- ## Key Concepts to Remember | Concept | Plain English | |---------|---------------| | **Master Recording** | The recorded performance — owned by label or artist | | **Composition** | The song itself (melody + lyrics) — owned by songwriter/publisher | | **Mechanical Royalty** | Paid for reproducing a composition (streams, downloads, physical) | | **Performance Royalty** | Paid for publicly performing a composition (radio, streaming, live) | | **Sync Royalty** | Paid for licensing a song for use with visual media | | **PRO** | Performing Rights Organization — collects and distributes performance royalties | | **MLC** | Mechanical Licensing Collective — U.S. digital mechanicals | | **ISWC** | Identifies the composition (publishing equivalent of ISRC) | | **Black Box** | Unclaimed royalties redistributed to eligible rights holders | | **Controlled Composition** | A song written by the recording artist — often subject to reduced mechanical rates | | **Writer Share** | The songwriter's portion of publishing royalties (typically 50%) | | **Publisher Share** | The publisher's portion of publishing royalties (typically 50%) | | **Co-publishing** | Artist partially owns their publishing rights alongside the publisher | --- ## What We Can Look Up Live | Question | Tool | |----------|------| | Publishing rights and ownership splits for an ISRC | `graphql_explore_skill` | | ISWC registration for a composition | `graphql_explore_skill` | | Sync adjustment posted to an account | `revenue_overview_skill` | | PRO or mechanical adjustment history | `revenue_overview_skill` | | Publisher advance balance and recoupment | `contract_overview_skill` | | Black box distributions for an account | `revenue_overview_skill` | | Composition metadata and writer shares | `graphql_explore_skill` | --- # Chapter 2b: Contracts & Terms — The Deal Structure The **contract** is the legal and financial backbone of every account in Abacus. It defines the rules of the deal — what royalty rates apply, which stores and territories are covered, how advances are structured, and how revenue is split between the account holder and Sony Music. Everything in the royalty engine flows from the contract. --- ## What Is a Contract? A contract in Abacus is the digital representation of a signed deal. It links an account to a set of **terms and conditions** that the royalty engine uses to calculate how much of each revenue dollar belongs to the account holder. Every contract: - Belongs to exactly one **account** - Has one or more **terms** (rate structures) - Each term has one or more **conditions** (specific rates for specific scenarios) - May have one or more **advances** (upfront money to recoup) - Has a defined **lifecycle** (active, expired, terminated) - Is governed by a **run controller** (determines when it processes) --- ## Contract Fields | Field | Description | |------------------------|----------------------------------------------------------------| | **Contract ID** | Unique numeric identifier | | **Contract Name** | Human-readable label for the deal | | **Account ID** | The account this contract belongs to | | **Contract Type** | Distribution, License, Joint Venture, Publishing, etc. | | **Status** | Active, Expired, Terminated, Draft | | **Effective Date** | When the contract starts | | **Expiry Date** | When the contract ends (if applicable) | | **Base Currency** | The currency royalties are calculated in | | **Is Base Contract** | Whether this is the primary/default contract for the account | --- ## Contract Status | Status | Meaning | |-----------------|------------------------------------------------------------------| | **Active** | Contract is live — royalties are being calculated under it | | **Expired** | Contract end date has passed — no new royalties processed | | **Terminated** | Contract ended early — no new royalties processed | | **Draft** | Contract created but not yet activated | > An account can have **multiple active contracts simultaneously** — for example, > one for digital distribution and a separate one for physical distribution. --- ## Contract Terms A **term** is the rate structure within a contract. It defines the royalty percentage the account holder receives for a category of revenue. ### Term Fields | Field | Description | |------------------------|----------------------------------------------------------------| | **Term ID** | Unique numeric identifier | | **Term Name** | Human-readable label (e.g. "Label Term", "Digital Rate") | | **Term Type** | Label Term, Track Term, Publisher Term, etc. | | **Is Base Term** | Whether this is the default fallback term | | **Term Rate** | The royalty rate paid to the account holder (as a percentage) | | **Commission** | Sony's share (term_rate + commission = 100%) | | **Conditions** | The specific rules that define when this rate applies | ### Term Rate vs. Commission ``` Term Rate: 80% ← Account holder receives this share Commission: 20% ← Sony retains this share ──── Total: 100% On $1,000 net revenue: Account holder receives: $800 Sony retains: $200 ``` --- ## Contract Conditions A **condition** is the most granular level of a contract — the specific rate that applies under a defined set of circumstances. Every term has one or more conditions. ### Condition Fields | Field | Description | |---------------------------------|---------------------------------------------------------| | **Condition Name** | Human-readable label (may be null) | | **Term Rate** | Royalty rate for this specific condition | | **Commission** | Sony's share for this specific condition | | **Priority** | Evaluation order — lower number = checked first | | **Countries** | Territories where this condition applies | | **Stores** | DSPs where this condition applies | | **Transaction Types** | Revenue categories where this condition applies | ### Condition Matching — How the Engine Picks a Rate When revenue arrives, the royalty engine matches it to the correct condition by checking three dimensions simultaneously: ``` Revenue Event: Store: Spotify Territory: US Transaction Type: ADA (Ad-Disabled Audio Stream) │ ▼ Engine checks conditions in priority order: Priority 1: Applies to Spotify + US + ADA? → YES → Use this rate ✅ Priority 2: (not evaluated — priority 1 matched) Priority 3: (not evaluated — priority 1 matched) │ ▼ Term Rate: 80% applied to this revenue event ``` If no specific condition matches, the **base term** acts as the fallback. --- ## Transaction Types **Transaction types** define the category of music consumption — what kind of activity generated the revenue. Each has a short **code** and a full **name**: | Code | Name | Description | |---------|------------------------------------|----------------------------------------| | **ADA** | Ad-Disabled Audio Streams | Paid subscription audio streams | | **AEA** | Ad-Enabled Audio Streams | Free-tier audio streams with ads | | **ADV** | Ad-Disabled Video Streams | Paid subscription video streams | | **AEV** | Ad-Enabled Video Streams | Free-tier video streams with ads | | **DPD** | Digital Permanent Download | Paid track/album download (own forever)| | **LTD** | Limited Download | Tethered/offline download (subscription)| | **RBT** | Ringtone / Ringback Tone | Mobile ringtone sale | | **SYN** | Sync | Sync licensing revenue | | **PHY** | Physical | Physical product sales (CD, vinyl) | > When a contract condition specifies transaction types, the royalty engine only > applies that rate when revenue matches one of those types. Conditions without > specified transaction types apply to **all** transaction types. --- ## Contract Parties A contract can have multiple **parties** — the entities involved in the deal beyond the primary account holder: | Party Type | Description | |------------------|------------------------------------------------------| | **Label** | The record label party to the contract | | **Artist** | The recording artist party to the contract | | **Publisher** | A publishing entity involved in the deal | | **Distributor** | The distribution entity | | **Joint Venture**| A partner in a shared deal | Parties are informational — they identify who is legally bound by the contract. --- ## Contract Advances Contracts can have one or more **advances** attached — upfront payments that must be recouped before royalties are paid out (see Chapter 6 for full detail). | Field | Description | |----------------------|----------------------------------------------------------| | **Advance ID** | Unique numeric identifier | | **Amount** | Original advance amount | | **Status** | Active, Fully Recouped, Written Off | | **Recouped Amount** | How much has been earned back | | **Unrecouped Balance**| Remaining amount: Amount − Recouped | | **Cross-Recoupment** | Whether revenue from other contracts can be applied | --- ## Contract Exclusions Some contracts include **exclusions** — specific products, territories, or stores that are explicitly carved out from the contract's terms: ``` Contract covers: All digital stores, worldwide Exclusion: ISRC US-S1Z-23-00001 excluded from Spotify → Revenue from that specific track on Spotify uses a different rate (or falls through to a separate contract) ``` Exclusions allow precise carve-outs without needing a separate contract for every edge case. --- ## Contract Lifecycle Every contract moves through a defined lifecycle: ``` Draft → Active → Expired / Terminated ``` | Event | Trigger | |---------------------|------------------------------------------------------| | **Activation** | Effective date reached or manually activated | | **Expiry** | Expiry date reached (if defined) | | **Termination** | Early end — artist/label departure, deal cancellation| | **Renewal** | New contract created to replace expiring one | When a contract expires or is terminated, the account's revenue falls through to the **base contract** (if one exists) or stops being processed under that deal. --- ## Run Controller The **run controller** determines whether a contract is included in the next royalty processing run. It acts as a gate: | Status | Meaning | |-------------|----------------------------------------------------------------| | **Enabled** | Contract will be included in the next processing run | | **Disabled**| Contract is excluded from processing — no royalties calculated | | **Locked** | Contract is locked pending review — cannot be modified | Internal teams can disable the run controller to pause processing on a contract without terminating it — useful during audits, disputes, or contract renegotiations. --- ## Multiple Contracts on One Account An account can have several contracts active simultaneously, each covering different scenarios: ``` Account: "Indie Artist LLC" (Account 12345) ├── Contract A: Digital Distribution (Active) │ └── Covers: All digital stores, worldwide, 80% rate ├── Contract B: Physical Distribution (Active) │ └── Covers: Physical sales, US only, 72% rate ├── Contract C: Sync Licensing (Active) │ └── Covers: Sync revenue, all territories, 75% rate └── Contract D: Legacy Deal (Expired) └── Covered: All revenue 2018–2022, 70% rate ``` When revenue arrives, the engine evaluates all active contracts and applies the most specific match based on store, territory, and transaction type. --- ## How Contracts Connect to Everything Else ``` Contract ├── Account (owner of the contract) ├── Terms │ └── Conditions │ ├── Countries → which territories this rate covers │ ├── Stores → which DSPs this rate covers │ └── Transaction Types → which revenue categories this rate covers ├── Advances │ └── Recoupment → blocks payment until earned back ├── Parties (label, artist, publisher, distributor) ├── Exclusions (specific products/stores carved out) ├── Lifecycle (effective date, expiry, termination) └── Run Controller (enables/disables processing) ``` --- ## Key Concepts to Remember | Concept | Plain English | |---------|---------------| | **Contract** | The digital deal — defines royalty rates for an account | | **Term** | A rate structure within the contract | | **Condition** | The specific rate for a specific store/territory/transaction type | | **Term Rate** | The account holder's percentage share | | **Commission** | Sony's percentage share (term rate + commission = 100%) | | **Priority** | The order conditions are evaluated — lower = checked first | | **Base Term** | The fallback rate when no specific condition matches | | **Transaction Type** | The category of consumption (ADA, AEV, DPD, etc.) | | **Run Controller** | The on/off switch for contract processing | | **Exclusion** | A specific carve-out from the contract's scope | --- ## What We Can Look Up Live With a **Contract ID**: - Full contract details (name, type, status, dates) - All terms with their rates and commission percentages - All conditions — countries, stores, and transaction types per condition - All advances (status, recouped, unrecouped balance) - Contract parties - Exclusions - Lifecycle history - Run controller status With an **Account ID**: - All contracts associated with the account - Quick overview of which contracts are active vs. expired --- # Chapter 13: GraphQL & Snowflake — Querying the Platform Abacus exposes data through two analytical query systems in addition to its REST APIs: **GraphQL** for cross-team federated data, and **Snowflake** for analytical SQL queries against the data warehouse. Knowing when to use each — and how to use them effectively — unlocks data that isn't available through any named REST tool. --- ## Two Query Systems, Two Purposes | System | Best For | |---------------|-------------------------------------------------------------------| | **GraphQL** | Cross-team and cross-domain data: publishing rights, ownership, identity, DSP delivery, label relationships | | **Snowflake** | Analytics, aggregations, trends, stream counts, rankings, custom breakdowns | They are **complementary, not competing**. A complete answer often draws from both: - GraphQL tells you *what* a thing is and *who* owns it - Snowflake tells you *how much*, *how many*, and *how it compares over time* --- ## GraphQL — Federated Cross-Team Data ### What Is GraphQL? GraphQL is a query language for APIs. Unlike REST (which has fixed endpoints), GraphQL lets you ask for exactly the fields you need in a single request — no more, no less. Abacus uses a **federated GraphQL gateway** — a single entry point that combines data from multiple internal services into one unified schema. Teams across Sony (publishing, ownership, distribution, identity) expose their data here. ### When to Use GraphQL Use GraphQL when the question spans **multiple services or teams**: | Question | Why GraphQL | |----------|-------------| | "What publishing rights are associated with this track?" | Publishing service data | | "Who owns the master recording for this ISRC?" | Ownership/rights data | | "What label is this artist signed to?" | Label relationship data | | "Has this product been delivered to Spotify?" | DSP delivery data | | "What is the user's identity across Sony systems?" | Identity federation | | "What are the contract terms in the royalties system?" | Abacus contract data | ### How GraphQL Queries Work ``` You describe what you want: query { product(id: "12345") { name upc artist { name } label { name country } } } GraphQL returns exactly that — nothing more, nothing less: { "product": { "name": "Midnight Sessions", "upc": "888003244085", "artist": { "name": "The Smith Band" }, "label": { "name": "Indie Records", "country": "US" } } } ``` ### GraphQL Schema Concepts | Concept | Description | |---------|-------------| | **Query** | A read operation — fetching data | | **Type** | A data shape — defines what fields are available | | **Field** | A single piece of data on a type | | **Argument** | An input to a query or field (e.g. `id: "12345"`) | | **Resolver** | The service that provides the data for a field | | **Federation** | Multiple services stitched into one unified schema | | **Null field** | Normal in federated schemas — means access-restricted or not applicable | ### GraphQL Workflow ``` Step 1: Explore graphql_explore_skill(search_term: "publishing rights") → Returns matching query fields, types, and a suggestedQuery Step 2: Execute (auto or manual) Option A (1 round): graphql_explore_skill with auto_execute: true + variables Option B (2 rounds): graphql_explore_skill → query_graphql(suggestedQuery) Step 3: Present results Strip null fields. Present non-null data clearly. Partial nulls are normal — not a failure. ``` ### GraphQL Business Term Glossary The explore skill understands business language: | You Say | GraphQL Finds | |---------|---------------| | "royalties" | abacusContract / abacusContracts | | "distribution" | delivery / deliveryStores | | "product" | product / products | | "user" | identityByEmail / identityById | | "publishing" | publishingRights / publishingContract | | "ownership" | ownershipSplits / masterRights | | "label" | labelRelationship / labelGroup | ### GraphQL Error Handling | Error | What To Do | |-------|------------| | **400 / schema validation** | Do not retry — fall back to REST or tell the user | | **Partial nulls** | Normal — present whatever non-null data was returned | | **Empty results** | Try one alternative search term before giving up | | **Access denied** | Note it briefly — do not retry with different credentials | --- ## Snowflake — Data Warehouse Analytics ### What Is Snowflake? Snowflake is a cloud data warehouse. It stores large volumes of historical data — revenue, streams, contracts, products, balances — and allows SQL queries to aggregate, filter, sort, and compare across the entire catalog. Where REST APIs give you data for one entity at a time, Snowflake lets you ask: - "Show me ALL accounts with revenue above $100K this year" - "Which 10 DSPs generated the most revenue last quarter?" - "How many streams did the catalog get by country in 2024?" - "Compare two artists' revenue over the last 12 months" ### When to Use Snowflake Use Snowflake for **analytical, comparative, or catalog-wide** questions: | Question | Why Snowflake | |----------|---------------| | "What are the top 10 stores by revenue?" | Aggregation across all accounts | | "How many streams came from Spotify last month?" | Stream count data | | "Which accounts have unrecouped advances over $1M?" | Cross-account filter | | "Show me revenue trend by month for the last year" | Time-series aggregation | | "What are the most played tracks in the catalog?" | Catalog-wide ranking | | "Compare net revenue for two accounts" | Multi-entity comparison | ### Snowflake Key Tables | Business Term | Table | Description | |---------------|-------|-------------| | Revenue | VW_REVENUE_BY_COUNTRY | Revenue broken down by territory | | Contract | VW_OA_CONTRACT | Contract data for analytics | | Balance | VW_ABACUS_BALANCES_LOOKER_V2 | Account balance snapshots | | Vendor | VW_DIM_ABACUS_AR_VENDOR | Account/vendor dimension | | Flowthrough | VW_ABACUS_AUTOMATED_FLOWTHROUGH | Flowthrough payment data | > Always use **fully-qualified table names**: `DATABASE.SCHEMA.TABLE` > Always include a **LIMIT clause** — never run unbounded queries. ### Snowflake Workflow ``` Step 1: Explore snowflake_explore_skill(search_term: "revenue by store") → Returns matching tables, column schemas, FK relationships, and a ready-to-use suggestedQuery Step 2: Execute query_snowflake(sql: suggestedQuery) → Returns rows of data Step 3: Present results Summarize key figures. Use tables for comparisons. Use charts for trends and rankings (see Chapter 14). ``` ### Snowflake SQL Patterns #### Simple Lookup ```sql SELECT ACCOUNT_ID, ACCOUNT_NAME, NET_REVENUE_USD FROM DATABASE.SCHEMA.VW_DIM_ABACUS_AR_VENDOR WHERE ACCOUNT_ID = 12345 LIMIT 10; ``` #### Aggregation (Top Stores by Revenue) ```sql SELECT STORE_NAME, SUM(NET_REVENUE_USD) AS TOTAL_REVENUE FROM DATABASE.SCHEMA.VW_REVENUE_BY_STORE WHERE STATEMENT_PERIOD_YEAR = 2024 GROUP BY STORE_NAME ORDER BY TOTAL_REVENUE DESC LIMIT 10; ``` #### Time-Series Trend ```sql SELECT STATEMENT_PERIOD_NAME, SUM(NET_REVENUE_USD) AS MONTHLY_REVENUE FROM DATABASE.SCHEMA.VW_REVENUE_BY_PERIOD WHERE ACCOUNT_ID = 12345 GROUP BY STATEMENT_PERIOD_NAME ORDER BY STATEMENT_PERIOD_NAME ASC LIMIT 24; ``` #### Cross-Account Comparison ```sql SELECT ACCOUNT_ID, ACCOUNT_NAME, SUM(NET_REVENUE_USD) AS TOTAL_REVENUE FROM DATABASE.SCHEMA.VW_REVENUE_BY_STORE WHERE ACCOUNT_ID IN (12345, 67890) AND STATEMENT_PERIOD_YEAR = 2024 GROUP BY ACCOUNT_ID, ACCOUNT_NAME ORDER BY TOTAL_REVENUE DESC LIMIT 10; ``` ### Snowflake Business Term Glossary | You Say | Snowflake Finds | |---------|-----------------| | "revenue" | VW_REVENUE_BY_COUNTRY, VW_REVENUE_BY_STORE | | "streams" | Stream count tables in analytics schema | | "contract" | VW_OA_CONTRACT | | "balance" | VW_ABACUS_BALANCES_LOOKER_V2 | | "vendor" / "account" | VW_DIM_ABACUS_AR_VENDOR | | "flowthrough" | VW_ABACUS_AUTOMATED_FLOWTHROUGH | | "product" | Product dimension tables | | "period" | Statement period / accounting calendar tables | --- ## Choosing Between GraphQL and Snowflake ``` Is the question about a specific named entity (account, contract, product, rights holder)? │ ├── YES, and it spans multiple teams/services │ → GraphQL │ ├── YES, and it's a known REST entity │ → Use the named REST skill │ (account_overview, contract_overview, etc.) │ └── NO — it's analytical, comparative, or catalog-wide → Snowflake ``` ### Fan Out When Uncertain When the domain is unclear, query **both simultaneously**: ``` Turn 1: graphql_explore_skill(search_term: "...", auto_execute: false) snowflake_explore_skill(search_term: "...") Turn 2 (if both returned useful results): Run both queries in the same turn. Presentation: ### From GraphQL [GraphQL results] ### From Snowflake [Snowflake results] ``` Never silently mix totals from different sources. Always label which system each figure came from. --- ## Stream Counts vs. Revenue — Critical Distinction This distinction prevents the most common data source error: | Data Type | Source | Description | |-----------|--------|-------------| | **Revenue** (dollars earned) | Financial service / REST | Money paid by DSPs | | **Stream counts** (play quantities) | Snowflake only | Number of times content was played | > The financial service has **no stream count data**. It only returns money earned. > When a user asks "how many streams on Spotify?" — always use Snowflake. --- ## Platform-Wide vs. Account-Specific Queries | Query Type | Requires Account ID? | Source | |------------|:--------------------:|--------| | "Revenue for Account 12345" | ✅ Yes | REST skill or Snowflake | | "Top 10 stores by revenue this month" | ❌ No | Snowflake | | "Most streamed tracks in the catalog" | ❌ No | Snowflake | | "Publishing rights for ISRC US-S1Z-23-00001" | ❌ No | GraphQL | | "Has product 888003244085 been delivered to Spotify?" | ❌ No | GraphQL | Platform-wide queries go directly to Snowflake or GraphQL — no account ID needed. --- ## Key Concepts to Remember | Concept | Plain English | |---------|---------------| | **GraphQL** | Cross-team federated queries — rights, ownership, identity, delivery | | **Snowflake** | Analytical SQL — trends, rankings, stream counts, cross-account comparisons | | **Federation** | Multiple services stitched into one GraphQL schema | | **suggestedQuery** | Auto-generated query from the explore skill — use it directly | | **Fan out** | Query both systems simultaneously when the domain is unclear | | **Stream counts** | Snowflake only — the financial service has no play quantity data | | **Partial nulls** | Normal in GraphQL — access-restricted or not applicable fields | | **LIMIT clause** | Always required in Snowflake — never run unbounded queries | --- # Chapter 14: Putting It All Together — End-to-End Royalty Flow Every chapter in this guide has covered one piece of the Abacus puzzle. This final chapter assembles all those pieces into a single, continuous picture — tracing a dollar from the moment a fan presses play to the moment it lands in an artist's bank account. Understanding this flow end-to-end is what separates a user of Abacus from someone who truly understands it. --- ## The Cast of Characters Before tracing the flow, here's every entity involved and where it was covered: | Entity | Role | Chapter | |--------|------|---------| | **Product / ISRC / UPC** | The music being consumed | 9 | | **DSP / Store** | Platform where consumption happens (Spotify, Apple Music, etc.) | 4 | | **Transaction Type** | Category of consumption (ADA, AEV, DPD, etc.) | 12 | | **Revenue** | Money paid by DSPs for that consumption | 4 | | **Statement Period** | The accounting window revenue is bucketed into | 3 | | **Account** | The top-level entity that owns the music | 11 | | **Contract** | The deal that defines the royalty rate | 12 | | **Contract Term / Condition** | The specific rate for a store/territory/type | 12 | | **Ledger Balance** | The running financial position of the account | 5 | | **Advance** | Upfront money that must be recouped before payment | 6 | | **Adjustment** | Manual correction to the ledger | 8 | | **Tax Documentation** | Required compliance before payment | 10 | | **Payee** | Who receives the payment and where it goes | 10, 11 | | **Payment** | The actual disbursement | 7 | --- ## The End-to-End Flow ### Stage 1: A Fan Presses Play ``` Fan streams "Neon Lights" on Spotify (US, paid subscription) │ ├── Product: "Midnight Sessions" (UPC: 888003244085) ├── Track: "Neon Lights" (ISRC: US-S1Z-23-00001) ├── Store: Spotify ├── Territory: United States └── Transaction Type: ADA (Ad-Disabled Audio Stream) ``` Nothing has happened in Abacus yet. The consumption event is recorded by Spotify. --- ### Stage 2: DSP Reports Revenue At the end of the month, Spotify sends Sony a **revenue report** — a file listing every stream, download, and play, with the dollar amount owed per line item. ``` Spotify Revenue Report (March 2024): ISRC: US-S1Z-23-00001 Store: Spotify Territory: US Transaction Type: ADA Gross Revenue: $1,250.00 Distribution Fee: $250.00 (20% Sony commission) Net Revenue: $1,000.00 ``` --- ### Stage 3: Revenue Ingestion & Period Assignment Abacus ingests the DSP report and assigns the revenue to the correct **statement period** (see Chapter 3): ``` Revenue event: March 2024 Statement Period: 2024-03 (March 2024) Status: Open → Processing → Closed ``` The revenue is now visible in the account's activity for the 2024-03 period. --- ### Stage 4: Product → Account Resolution Abacus matches the ISRC to the correct account (see Chapter 9): ``` ISRC: US-S1Z-23-00001 │ ▼ Product: "Midnight Sessions" (UPC: 888003244085) │ ▼ Vendor ID: 12345 → Account: "Indie Artist LLC" ``` The revenue is now attributed to Account 12345. --- ### Stage 5: Contract & Rate Matching The royalty engine finds the correct contract and applies the matching condition (see Chapter 12): ``` Account 12345 → Contract A (Digital Distribution, Active) │ ▼ Engine evaluates conditions in priority order: Priority 1: Spotify + US + ADA → Term Rate: 80% │ ▼ Applied Rate: 80% On $1,000.00 net revenue: Account holder earns: $800.00 (80%) Sony retains: $200.00 (20% commission) ``` --- ### Stage 6: Ledger Posting The calculated royalty is posted to the account's **ledger** (see Chapter 5): ``` Account 12345 — Ledger Entry (2024-03): + $800.00 Net Royalty Credit (Spotify / US / ADA) ``` If the account has an **advance** outstanding, the credit is first applied against the unrecouped balance (see Chapter 6): ``` Advance Balance Before: −$50,000.00 (unrecouped) Royalty Credit: +$800.00 Advance Balance After: −$49,200.00 (still unrecouped) → No payment yet — advance not fully recouped ``` This continues every period until the advance is fully recouped. --- ### Stage 7: Adjustments (If Needed) Before the period closes, internal teams may apply **manual adjustments** to correct errors, apply fees, or transfer revenue (see Chapter 8): ``` Example: DSP underreported revenue for January — correction applied in March Adjustment Row: Account: 12345 Contract: Contract A Type: Adjustment Amount: +$500.00 Activity Month: January 2024 Statement Month: March 2024 Note: "Spotify underreport correction — Ticket #4521" Ledger after adjustment: Net Royalty Credit: $800.00 Adjustment Credit: $500.00 Period Total Credit: $1,300.00 ``` --- ### Stage 8: Period Close & Balance Calculation At the end of the statement period, Abacus closes the books: ``` Period: 2024-03 Revenue Credits: +$800.00 (royalties) Adjustments: +$500.00 (correction) Fees/Debits: −$50.00 (admin fee) ───────── Period Net: +$1,250.00 Running Balance (before this period): −$49,200.00 (unrecouped advance) Running Balance (after this period): −$47,950.00 (still unrecouped) ``` --- ### Stage 9: Payment Eligibility Check When the period closes, Abacus evaluates whether the account is eligible for payment (see Chapters 7, 10, 11): ``` Eligibility Checklist: ✅ Tax documentation on file (W-9, valid, not expired) ✅ Payee configured (Wire / Chase Bank / USD) ✅ No Tax Hold active ✅ No Payee Hold active ✅ No Manual Payment Hold active ❌ Advance not fully recouped → Balance still negative Result: No payment — balance rolls forward to next period ``` Once the advance is fully recouped: ``` Eligibility Checklist: ✅ Tax documentation valid ✅ Payee configured ✅ No holds active ✅ Advance fully recouped ✅ Balance exceeds payment threshold ($100 minimum) Result: Payment created ✅ Amount: $2,450.00 Method: Wire Transfer Currency: USD Payee: "Smith Band Management LLC" Bank: Chase Bank, Account #123456789 ``` --- ### Stage 10: Payment Disbursed The payment is sent to the payee's bank account. The ledger is updated: ``` Account 12345 — Ledger Entry (Payment): − $2,450.00 Payment Disbursed (Wire / Chase / USD) Balance after payment: $0.00 ``` The cycle begins again with the next statement period. --- ## The Full Flow — One Diagram ``` Fan Presses Play │ ▼ DSP Records Stream │ ▼ DSP Reports Revenue to Sony (monthly) │ ▼ Revenue Ingested → Assigned to Statement Period │ ▼ ISRC / UPC → Product → Account (via vendor_id) │ ▼ Contract Matched → Condition Evaluated → Rate Applied │ ▼ Net Royalty Calculated (Revenue × Term Rate) │ ▼ Posted to Ledger │ ├── Advance Outstanding? → Recoup First → Balance Still Negative │ │ │ └── Roll Forward to Next Period │ └── No Advance (or Fully Recouped) → Balance Positive │ ▼ Adjustments Applied (if any) │ ▼ Period Closes → Balance Calculated │ ▼ Eligibility Check ├── Tax Hold? → Block ├── Payee Hold? → Block ├── Manual Hold? → Block ├── Below Threshold? → Roll Forward └── All Clear ✅ │ ▼ Payment Created → Disbursed to Payee's Bank Account ``` --- ## Common Scenarios & Where They Break Understanding the flow means understanding where it can stall: | Symptom | Likely Cause | Where to Look | |---------|-------------|---------------| | Balance growing but no payment | Advance not recouped | Chapter 6 — Advances | | Balance growing but no payment | Tax Hold active | Chapter 10 — Tax Setup | | Balance growing but no payment | Payee Hold active | Chapter 10 — Payee Setup | | Balance growing but no payment | Manual payment hold | Chapter 7 — Payment Holds | | Balance growing but no payment | Below payment threshold | Chapter 11 — Payment Terms | | Revenue missing for a period | DSP report not yet ingested | Chapter 3 — Statement Periods | | Revenue lower than expected | Wrong contract condition applied | Chapter 12 — Contract Terms | | Revenue lower than expected | Commission rate incorrect | Chapter 12 — Contract Terms | | Payment went to wrong bank | Payee details incorrect | Chapter 10, 11 — Payee Setup | | Revenue attributed to wrong account | ISRC/UPC mapped to wrong vendor | Chapter 9 — Products | | Period revenue looks wrong | Adjustment applied incorrectly | Chapter 8 — Adjustments | --- ## How the Tools Map to the Flow | Stage in Flow | Best Tool | |---------------|-----------| | Look up a product by ISRC or UPC | `get_products_by_isrc` / `get_product_by_upc` | | Get account overview | `account_overview_skill` | | Check revenue by period or store | `revenue_overview_skill` | | Review contract terms and rates | `contract_overview_skill` | | Check ledger balance | `get_account_current_balance` | | Review advance recoupment status | `contract_overview_skill` | | Submit or review adjustments | Adjustment tools (Chapter 8) | | Check tax status and holds | `account_overview_skill` | | Check payee details | Account / payee tools | | Check payment eligibility | `account_overview_skill` | | Analytical / catalog-wide queries | `snowflake_explore_skill` | | Cross-team / rights / delivery queries | `graphql_explore_skill` | --- ## The Golden Rules of Abacus These are the principles that underpin everything in this guide: 1. **No account, no royalties.** Every dollar of revenue is attributed to an account via the product's vendor_id. If the product isn't mapped correctly, the money goes nowhere useful. 2. **No contract, no rate.** Revenue without a matching contract condition falls through to the base term — or isn't processed at all. Contracts must be active and correctly configured. 3. **Advances block payments.** An unrecouped advance is not a hold — it's a negative balance. Revenue credits it down. No payment until it reaches zero. 4. **Tax + Payee = Payment eligible.** Both must be in place simultaneously. One missing piece blocks everything, regardless of balance. 5. **Statement periods are the unit of time.** Revenue, adjustments, and payments all live within a period. Period IDs have no inherent date meaning — always resolve them to period names. 6. **Gross ≠ Net.** Gross revenue is before Sony's commission. Net is after. Always label which is which. Always include the currency code. 7. **Adjustments are the escape valve.** When the automated engine gets it wrong, adjustments fix it — but they require explicit confirmation, clear calculation workings, and the right statement period. 8. **Activity date ≠ Statement date.** When revenue happened and when it's booked are two different things. Retroactive corrections are common — always confirm both dates. 9. **Stream counts live in Snowflake.** The financial service returns dollars only. For play quantities and platform stream counts, always use Snowflake. 10. **The ledger is the source of truth.** When in doubt about an account's financial position, look at the ledger — it captures every credit, debit, advance, adjustment, and payment in one running total. # Chapter 13: Putting It All Together — End-to-End Royalty Flow Every chapter in this guide has covered one piece of the Abacus puzzle. This final chapter assembles all those pieces into a single, continuous picture — tracing a dollar from the moment a fan presses play to the moment it lands in an artist's bank account. Understanding this flow end-to-end is what separates a user of Abacus from someone who truly understands it. --- ## The Cast of Characters Before tracing the flow, here's every entity involved and where it was covered: | Entity | Role | Chapter | |--------|------|---------| | **Product / ISRC / UPC** | The music being consumed | 9 | | **DSP / Store** | Platform where consumption happens (Spotify, Apple Music, etc.) | 4 | | **Transaction Type** | Category of consumption (ADA, AEV, DPD, etc.) | 2 | | **Revenue** | Money paid by DSPs for that consumption | 4 | | **Statement Period** | The accounting window revenue is bucketed into | 3 | | **Account** | The top-level entity that owns the music | 1 | | **Contract** | The deal that defines the royalty rate | 2 | | **Contract Term / Condition** | The specific rate for a store/territory/type | 2 | | **Ledger Balance** | The running financial position of the account | 5 | | **Advance** | Upfront money that must be recouped before payment | 6 | | **Adjustment** | Manual correction to the ledger | 8 | | **Publishing & Sync** | Composition rights and licensing revenue | 11 | | **Tax Documentation** | Required compliance before payment | 10 | | **Payee** | Who receives the payment and where it goes | 1, 10 | | **Payment** | The actual disbursement | 7 | | **GraphQL & Snowflake** | Cross-team and analytical queries across the platform | 12 | --- ## The End-to-End Flow ### Stage 1: A Fan Presses Play ``` Fan streams "Neon Lights" on Spotify (US, paid subscription) │ ├── Product: "Midnight Sessions" (UPC: 888003244085) ├── Track: "Neon Lights" (ISRC: US-S1Z-23-00001) ├── Store: Spotify ├── Territory: United States └── Transaction Type: ADA (Ad-Disabled Audio Stream) ``` Nothing has happened in Abacus yet. The consumption event is recorded by Spotify. --- ### Stage 2: DSP Reports Revenue At the end of the month, Spotify sends Sony a **revenue report** — a file listing every stream, download, and play, with the dollar amount owed per line item. ``` Spotify Revenue Report (March 2024): ISRC: US-S1Z-23-00001 Store: Spotify Territory: US Transaction Type: ADA Gross Revenue: $1,250.00 Distribution Fee: $250.00 (20% Sony commission) Net Revenue: $1,000.00 ``` --- ### Stage 3: Revenue Ingestion & Period Assignment Abacus ingests the DSP report and assigns the revenue to the correct **statement period** (see Chapter 3): ``` Revenue event: March 2024 Statement Period: 2024-03 (March 2024) Status: Open → Processing → Closed ``` The revenue is now visible in the account's activity for the 2024-03 period. --- ### Stage 4: Product → Account Resolution Abacus matches the ISRC to the correct account (see Chapter 9): ``` ISRC: US-S1Z-23-00001 │ ▼ Product: "Midnight Sessions" (UPC: 888003244085) │ ▼ Vendor ID: 12345 → Account: "Indie Artist LLC" ``` The revenue is now attributed to Account 12345. --- ### Stage 5: Contract & Rate Matching The royalty engine finds the correct contract and applies the matching condition (see Chapter 2): ``` Account 12345 → Contract A (Digital Distribution, Active) │ ▼ Engine evaluates conditions in priority order: Priority 1: Spotify + US + ADA → Term Rate: 80% │ ▼ Applied Rate: 80% On $1,000.00 net revenue: Account holder earns: $800.00 (80%) Sony retains: $200.00 (20% commission) ``` --- ### Stage 6: Ledger Posting The calculated royalty is posted to the account's **ledger** (see Chapter 5): ``` Account 12345 — Ledger Entry (2024-03): + $800.00 Net Royalty Credit (Spotify / US / ADA) ``` If the account has an **advance** outstanding, the credit is first applied against the unrecouped balance (see Chapter 6): ``` Advance Balance Before: −$50,000.00 (unrecouped) Royalty Credit: +$800.00 Advance Balance After: −$49,200.00 (still unrecouped) → No payment yet — advance not fully recouped ``` This continues every period until the advance is fully recouped. --- ### Stage 7: Adjustments (If Needed) Before the period closes, internal teams may apply **manual adjustments** to correct errors, apply fees, or transfer revenue (see Chapter 8): ``` Example: DSP underreported revenue for January — correction applied in March Adjustment Row: Account: 12345 Contract: Contract A Type: Adjustment Amount: +$500.00 Activity Month: January 2024 Statement Month: March 2024 Note: "Spotify underreport correction — Ticket #4521" Ledger after adjustment: Net Royalty Credit: $800.00 Adjustment Credit: $500.00 Period Total Credit: $1,300.00 ``` --- ### Stage 7b: Publishing & Sync Revenue (If Applicable) If the account also earns **publishing or sync revenue** (see Chapter 11), those amounts are posted separately — either as automated revenue or as manual adjustments: ``` Sync License (Master Fee): Account: 12345 Adjustment Type: Sync License Amount: +$50,000.00 Note: "Paramount trailer placement — March 2024" Performance Royalty (PRO Distribution): Account: 12345 Adjustment Type: Performance Royalties Amount: +$1,200.00 Note: "ASCAP Q1 2024 distribution" ``` These credits post to the ledger alongside streaming royalties and are subject to the same recoupment and eligibility rules. --- ### Stage 8: Period Close & Balance Calculation At the end of the statement period, Abacus closes the books: ``` Period: 2024-03 Revenue Credits: +$800.00 (royalties) Adjustments: +$500.00 (correction) Fees/Debits: −$50.00 (admin fee) ───────── Period Net: +$1,250.00 Running Balance (before this period): −$49,200.00 (unrecouped advance) Running Balance (after this period): −$47,950.00 (still unrecouped) ``` --- ### Stage 9: Payment Eligibility Check When the period closes, Abacus evaluates whether the account is eligible for payment (see Chapters 7, 1, 10): ``` Eligibility Checklist: ✅ Tax documentation on file (W-9, valid, not expired) ✅ Payee configured (Wire / Chase Bank / USD) ✅ No Tax Hold active ✅ No Payee Hold active ✅ No Manual Payment Hold active ❌ Advance not fully recouped → Balance still negative Result: No payment — balance rolls forward to next period ``` Once the advance is fully recouped: ``` Eligibility Checklist: ✅ Tax documentation valid ✅ Payee configured ✅ No holds active ✅ Advance fully recouped ✅ Balance exceeds payment threshold ($100 minimum) Result: Payment created ✅ Amount: $2,450.00 Method: Wire Transfer Currency: USD Payee: "Smith Band Management LLC" Bank: Chase Bank, Account #123456789 ``` --- ### Stage 10: Payment Disbursed The payment is sent to the payee's bank account. The ledger is updated: ``` Account 12345 — Ledger Entry (Payment): − $2,450.00 Payment Disbursed (Wire / Chase / USD) Balance after payment: $0.00 ``` The cycle begins again with the next statement period. --- ## The Full Flow — One Diagram ``` Fan Presses Play │ ▼ DSP Records Stream │ ▼ DSP Reports Revenue to Sony (monthly) │ ▼ Revenue Ingested → Assigned to Statement Period (Ch. 3) │ ▼ ISRC / UPC → Product → Account via vendor_id (Ch. 9) │ ▼ Contract Matched → Condition Evaluated → Rate Applied (Ch. 2) │ ▼ Net Royalty Calculated (Revenue × Term Rate) │ ▼ Posted to Ledger (Ch. 5) │ ├── Advance Outstanding? → Recoup First (Ch. 6) → Balance Still Negative │ │ │ └── Roll Forward to Next Period │ └── No Advance (or Fully Recouped) → Balance Positive │ ▼ Adjustments Applied if needed (Ch. 8) Publishing / Sync credits applied if applicable (Ch. 11) │ ▼ Period Closes → Balance Calculated (Ch. 3) │ ▼ Eligibility Check (Ch. 7, 10) ├── Tax Hold? → Block ├── Payee Hold? → Block ├── Manual Hold? → Block ├── Below Threshold? → Roll Forward └── All Clear ✅ │ ▼ Payment Created → Disbursed to Payee's Bank Account (Ch. 1, 10) ``` --- ## Common Scenarios & Where They Break Understanding the flow means understanding where it can stall: | Symptom | Likely Cause | Chapter | |---------|-------------|---------| | Balance growing but no payment | Advance not recouped | 6 | | Balance growing but no payment | Tax Hold active | 10 | | Balance growing but no payment | Payee Hold active | 10 | | Balance growing but no payment | Manual payment hold | 7 | | Balance growing but no payment | Below payment threshold | 1 | | Revenue missing for a period | DSP report not yet ingested | 3 | | Revenue lower than expected | Wrong contract condition applied | 2 | | Revenue lower than expected | Commission rate incorrect | 2 | | Payment went to wrong bank | Payee details incorrect | 1, 10 | | Revenue attributed to wrong account | ISRC/UPC mapped to wrong vendor | 9 | | Period revenue looks wrong | Adjustment applied incorrectly | 8 | | Sync fee missing from account | Sync adjustment not posted | 11 | | Publishing royalty not received | PRO distribution not yet applied | 11 | --- ## How the Tools Map to the Flow | Stage in Flow | Best Tool | |---------------|-----------| | Look up a product by ISRC or UPC | `get_products_by_isrc` / `get_product_by_upc` | | Get account overview | `account_overview_skill` | | Check revenue by period or store | `revenue_overview_skill` | | Review contract terms and rates | `contract_overview_skill` | | Check ledger balance | `get_account_current_balance` | | Review advance recoupment status | `contract_overview_skill` | | Submit or review adjustments | Adjustment tools (Ch. 8) | | Check tax status and holds | `account_overview_skill` | | Check payee details | `account_overview_skill` | | Check payment eligibility | `account_overview_skill` | | Look up publishing rights or sync data | `graphql_explore_skill` (Ch. 12) | | Analytical / catalog-wide queries | `snowflake_explore_skill` (Ch. 12) | --- ## The Golden Rules of Abacus These are the principles that underpin everything in this guide: 1. **No account, no royalties.** Every dollar of revenue is attributed to an account via the product's vendor_id. If the product isn't mapped correctly, the money goes nowhere useful. 2. **No contract, no rate.** Revenue without a matching contract condition falls through to the base term — or isn't processed at all. Contracts must be active and correctly configured. 3. **Advances block payments.** An unrecouped advance is not a hold — it's a negative balance. Revenue credits it down. No payment until it reaches zero. 4. **Tax + Payee = Payment eligible.** Both must be in place simultaneously. One missing piece blocks everything, regardless of balance. 5. **Statement periods are the unit of time.** Revenue, adjustments, and payments all live within a period. Period IDs have no inherent date meaning — always resolve them to period names. 6. **Gross ≠ Net.** Gross revenue is before Sony's commission. Net is after. Always label which is which. Always include the currency code. 7. **Adjustments are the escape valve.** When the automated engine gets it wrong, adjustments fix it — but they require explicit confirmation, clear calculation workings, and the right statement period. 8. **Activity date ≠ Statement date.** When revenue happened and when it's booked are two different things. Retroactive corrections are common — always confirm both dates. 9. **Stream counts live in Snowflake.** The financial service returns dollars only. For play quantities and platform stream counts, always use Snowflake (Ch. 12). 10. **The ledger is the source of truth.** When in doubt about an account's financial position, look at the ledger — it captures every credit, debit, advance, adjustment, and payment in one running total.