# Royalty dispute records: cross-system key map | SourceX

Canonical: https://refer.sourcex.si/guides/royalty-reconciliation-disputes-records-across-systems
Last updated: 2026-10-19

Reconstructing a royalty dispute needs five joins: the refund to the payment it reverses, the payment to the location and reporting period, the period's report to the agreement version that set the rule, the short payment to its dispute ticket, and the ticket to the credit memo that settled it. The first join usually lives in the POS. The rest cross into the royalty platform, the franchise ERP and the agreement files, which is where most histories break.

This system map is part of the [royalty reconciliation disputes guide](/guides/workflow-royalty-reconciliation-disputes), which works through one refund that crossed a reporting period. Here the job is different: show which system holds each record, which identifier carries the case from one system to the next, and what a fully joined case looks like when every key survives.

## Five systems behind one royalty dispute

A franchisor's royalty dispute rarely sits in one tool. Each system holds one part of the story, and none holds the whole of it.

- **POS.** Transactions, refunds and the location they happened at. In Square's data model, for example, a Payment carries read-only fields for location_id, created_at, order_id and a list of refund_ids, so each payment knows which refunds were made against it.
- **Royalty platform.** The sales report as submitted for each location and period, the exclusion rules applied and the variance it flagged.
- **Franchise ERP.** The royalty invoice or statement, penalty fees, payments received and credit memos.
- **Agreement files.** Each franchise agreement version, its effective date and the locations signed under it. The fee table in each year's disclosure document (Item 6) states the royalty formula then in use, which helps date a rule when the signed copy is hard to find.
- **Dispute inbox or ticket queue.** The franchisee's challenge, the finance team's replies and the approval note.

## The key map: system, record, linking key, owner

This table is the evidence asset for the page. Read each row as "this record can be found from the previous one by this key".

| System | Record | Linking key it carries | Joins to | Usual owner |
|---|---|---|---|---|
| POS | Sale (payment) | Payment ID, location ID, created date | Refund; reporting period | POS administrator |
| POS | Refund | Original payment ID, refund ID | Sale it reverses | POS administrator |
| Royalty platform | Submitted sales report | Location ID, period, report ID | Agreement version; royalty invoice | Royalty analyst |
| Agreement files | Agreement version | Agreement ID, version, effective date, location list | Rule applied to the report | General counsel or franchise administration |
| Franchise ERP | Royalty invoice and penalty fee | Franchisee account, location, period | Payment received; dispute | Accounts receivable |
| Dispute inbox | Challenge and reply thread | Ticket number, location, period | Credit memo | Franchise finance head |
| Franchise ERP | Credit memo | Ticket number or memo note, period credited | Dispute it settled | Accounts receivable |

Two keys carry most of the weight: **location plus period**, which joins the operational systems to the financial ones, and **the payment ID**, which is the only thing that ties a refund back to a sale in an earlier period. Because a refund in that kind of POS is created against the original payment, and one payment can carry more than one partial refund, the payment ID is also how an analyst counts every reduction that belongs to a single sale.

## One fully joined case, Illustrative

Illustrative only; the franchisor, amounts and dates are fictional. A 160-person casual dining franchisor charges a 5% royalty on net sales, reported monthly. One location sold a $2,600 group order on March 29, then issued two partial refunds after the March report was submitted.

| Step | System | Record | Key used to reach the next step |
|---|---|---|---|
| 1 | POS | Sale of $2,600, March 29 | Payment ID |
| 2 | POS | Partial refund of $650, April 4 | Original payment ID |
| 3 | POS | Partial refund of $150, April 12 | Original payment ID |
| 4 | Royalty platform | March report submitted April 5, covering March sales only | Location and period |
| 5 | Royalty platform | April report nets $800 of refunds; rule flags a $40 royalty shortfall | Agreement version |
| 6 | Agreement files | Version signed 2019: refunds reduce the period of the original sale | Location list |
| 7 | Dispute inbox | Operator challenges the April shortfall and penalty fee | Ticket number |
| 8 | Franchise ERP | $40 credit applied to March; penalty reversed; memo cites the ticket | Ticket number |

When all eight steps resolve, anyone can rebuild both positions and see why finance agreed. Remove the payment ID from step 2 and the April refunds cannot be tied to the March sale. Remove the agreement version from step 6 and nobody can show which rule applied. For a parallel in month-end close work, see [reconciliation exceptions as training data](/data-types/reconciliation-exceptions-ai-agent-training-data).

## Where the chain breaks, and what each break costs

| Break | Where it happens | What the history loses |
|---|---|---|
| Refunds arrive as a daily total | POS feed into the royalty platform | The sale behind each refund |
| Report overwritten when corrected | Royalty platform | What the franchisee originally claimed |
| Only the current rule stored | Royalty platform configuration | Which definition applied to an older location |
| Approval given by email | Finance mailbox | The reason behind the credit |
| Memo without a ticket reference | Franchise ERP | The link from credit to dispute |

Each break leaves records that still exist but no longer explain each other. A franchisor with the first and third breaks still has sales reports and credits; it has lost the reasoning. If the franchisor is being sold, that reasoning can matter well beyond finance, as [earnouts and their disputes](/questions/what-is-an-earnout) shows.

## Questions to ask the franchise finance head

Keep the conversation to whether each key exists, never to the records themselves:

1. Does the franchisor receive transaction-level POS data, daily totals or only the franchisee's report?
2. Does a refund in that feed carry the original payment ID?
3. Are submitted reports kept as submitted, alongside corrections?
4. Is each agreement version filed with its effective date and the locations on it?
5. Do credit memos reference the dispute ticket or approval note?
6. How many years does each answer hold for?

Rights are a separate question. Franchisee sales data comes from separate businesses under franchise agreements, so counsel and the executive team decide whether anything could ever be licensed; the [who-can-license tree](/questions/who-can-license-royalty-reconciliation-disputes-records) maps that path, and the [preservation timeline](/guides/preserve-royalty-reconciliation-disputes-records) shows which keys are lost first in a platform replacement. [Franchisor data monetization](/industries/franchisor-data-monetization) covers the sector more broadly, and [upfront license fee vs royalty](/compare/upfront-license-fee-vs-royalty) explains why the fee formula matters.

The introduced company needs 50+ full-time employees at peak (contractors excluded; franchisee staff work for separate companies), a documented operating history, rights to license the records and an authorized contact. Companies in the U.S., Canada and the EU qualify, as do companies in the UK, Australia, New Zealand, India, Singapore, South Africa, Latin America, the UAE and Saudi Arabia when at least 90% of the data is in English. Unknown until SourceX reviews it: buyer interest, the rights review result and any terms. Partners sign the Channel Partner Agreement before submitting introductions, and the first valid introduction within the 90-day window is credited when the company submits a verified application.

## Next step

> **Refer a company. Earn up to $100,000.** Default reward: 25% of Actual Supplier Payout, capped at $100,000 cumulatively per referred company. Eligibility and payment conditions apply, and a signed Schedule A or addendum can differ. A lead, meeting or signature alone does not trigger payment.

If the franchise finance head confirms that refunds still carry the payment ID and credits still cite their tickets, [register as a partner](/register), check the franchisor on [who qualifies](/who-qualifies) and read the [program terms](/terms) before the introduction.

## Sources

- https://developer.squareup.com/reference/square/objects/Payment
- https://developer.squareup.com/reference/square/refunds-api/refund-payment
- https://www.ecfr.gov/current/title-16/chapter-I/subchapter-D/part-436/subpart-C/section-436.5
- https://refer.sourcex.si/terms