Reconcile partner commissions between HubSpot and Introw

I want an app my partner ops team opens at the end of every month to reconcile partner commissions between HubSpot and Introw. Our commission spreadsheet always drifts from the CRM, so this is the catch-up audit surface where a human reviews each gap and approves the correction. HubSpot is read only in this app: the only records it writes are Introw commission lines and one Slack summary.

The main screen is a reconciliation table for a chosen date range, defaulting to the last complete calendar month, with a period picker at the top and three tabs. Tab one, Missing commission: HubSpot deals that closed won inside the period with no matching Introw commission line. Tab two, Orphan lines: Introw commission lines in the period with no matching closed won deal. Tab three, Amount mismatch: matched pairs where the commission amount does not equal the expected percentage of deal value, or where the currencies differ. Each tab shows a count badge, and the header shows totals for the period: number of gaps, total value at risk, and how many rows are still unresolved.

Handlers build the picture from both sides. On the HubSpot side, use Search Deals filtered to closed won deals with a close date inside the selected period, paging through all results. For each deal, use Get Deal with associations to resolve the associated partner company, then Get Company to read that company's domain and name. Let me configure in a settings panel which association label or deal property identifies the partner company, since some teams tag the partner as a second associated company and others use a custom deal property carrying the partner domain. On the Introw side, use List Partners to build a directory of partners keyed by their domain, and List Commission Lines to pull the current commission picture for the period. Both Introw list endpoints are cursor paginated with a limit between 1 and 100, so page until the next cursor is null, and back off and retry when a rate limit response comes back.

Match the two sides on partner domain, normalising to lowercase and stripping protocol and any www prefix before comparing. Within a matched partner, link a commission line to a specific deal when the line description or reference contains the deal name or deal id, and fall back to matching on partner plus close date proximity inside the period. Deals where no partner company could be resolved go into their own Unmatched deals group rather than being dropped silently, so the reviewer can see what the app could not classify.

Expected commission is deal amount multiplied by the commission rate, which I set globally in settings with optional overrides per partner tier. Introw amounts are decimal strings such as 500.00 paired with an ISO 4217 currency code, so parse them as decimals rather than floats, compare with a configurable rounding tolerance, and treat a currency code that differs from the deal currency as a mismatch in its own right instead of converting. Show both the recorded amount and the expected amount side by side on every mismatch row, with the difference highlighted.

Every row has inline actions. On a missing commission row, Create commission line opens a dialog prefilled with the partner, the expected amount formatted as a decimal string, the deal currency, and the deal name as the description, and calls Create a Commission Line once the reviewer confirms. On a mismatch row, Correct amount calls Update a Commission Line to set the amount and currency to the expected values, writing an internal note that records the reconciliation period and who approved it. On an orphan row, Decline line calls Decline a Commission Line with a categorised reason chosen from a dropdown, with a free text note. Every action needs an explicit click, and the row updates in place to show its new state.

Respect the commission line status rules. Statuses are EXPECTED, PENDING, IN_PAYOUT, and VOIDED. Voided lines cannot be edited, so render them read only with a Voided badge and no actions at all. Warn before editing a line that is already IN_PAYOUT, since it is attached to a payout in flight. Declining only works on a line attached to a payout and returns a validation error otherwise, so check attachment first and explain the situation in the row rather than firing a call that will fail. If declining a line would empty its payout, tell the reviewer in the confirm dialog that the payout itself will be declined too.

Add an Investigate this gap button on each row that kicks off a background agent. The agent pulls the full history of the deal with Get Deal and looks for related deals at the same company with Search Deals, then pulls that partner's other commission lines with List Commission Lines and reads individual lines with Get a Commission Line where it needs detail. It decides whether the gap is a genuine miss, a duplicate of a line logged against another deal, or a timing difference where the commission landed in an adjacent period, and writes a short recommendation with its reasoning and a confidence level back into the row. The recommendation appears inline under the row with a timestamp, and the reviewer can still take any action regardless of what it concluded. Several investigations can run at once and each row shows its own progress.

Persist reconciliation state per period so the team can work across several sittings: which rows have been actioned, which were dismissed as acceptable and why, agent recommendations, and reviewer notes. Keep a record of who did what and when. When the reviewer marks the period reconciled, require every row to be either actioned or explicitly dismissed with a reason, then post a summary to a configurable Slack channel with Send a Message, covering commission lines created, amounts corrected, lines declined, total value moved, rows dismissed, and who signed the period off. Lock the period read only afterwards, with a way to reopen it that is recorded in the audit trail.