Partner payout approval queue with Xero bill handoff

Build me a partner payout approval queue that our finance and partner ops teams work out of, so payout approvals stop happening in email threads. Introw is the system of record for payouts and commission lines, Xero is where the payable bill gets raised, and Slack is where each approval gets announced.

The app opens on a queue board of Introw payouts grouped into columns by stage: pending review, pending invoice, approved, scheduled, paid. A handler calls Introw List Payouts once per stage using the stage filter (PENDING_REVIEW, PENDING_INVOICE, APPROVED, SCHEDULED, PAID) and pages through the cursor until nextCursor is null. Each card shows the partner name, the total amount with its currency, the period the payout covers, and the number of commission lines on it. Each column header shows the count of payouts and the summed total, kept separate per currency so nothing is ever added across currencies. Include a refresh control on the board.

Clicking a payout opens a detail panel beside the board. The panel handler calls Get a Payout for the full record, List Commission Lines filtered to that payout id, and Get a Partner for the partner details. The panel header shows the partner, the payout total and currency, the period, the current stage and the partner purchase order number if one is set. Below it, a table lists every commission line behind the total: description, source amount, commission amount, currency, status (EXPECTED, PENDING, IN_PAYOUT or VOIDED) and created date. Show the sum of the listed lines next to the payout total and flag it visibly when the two do not match, so the reviewer sees every line behind the total before approving anything.

From that panel the reviewer can act. A stage picker advances the payout using Update a Payout, offering only the valid Introw stages (DRAFT, PENDING_REVIEW, PENDING_INVOICE, APPROVED, SCHEDULED, PENDING_PAYMENT, PAID, DECLINED, POSTPONED, BLOCKED, FAILED). An editable field sets the partner purchase order number, also through Update a Payout. Each line row has a detach action that calls Detach a Commission Line to send a questionable line back to the pending pool, and a decline action that calls Decline a Commission Line with a categorised reason chosen from a dropdown, required before the decline can be submitted. After any of these, re-fetch the payout and its lines so the panel and the card totals stay accurate.

Bake in two Introw rules. First, detaching or declining a line that is not attached to a payout returns a 422 error, so disable both actions on lines that are not currently attached and, if the error still comes back, surface the message plainly instead of failing silently. Second, declining every line on a payout auto-declines the payout itself, so when the reviewer is about to decline the last remaining attached line, warn them first with an explicit confirmation along the lines of "This is the last line on this payout. Declining it will decline the whole payout." Once it goes through, move the card out of its column and refresh the board.

When a payout reaches the approved stage, show a button on the panel that creates the matching bill in Xero. The handler looks the partner up as a Xero contact with List Contacts by name, creates one as a supplier with Create Contacts if there is no match, then calls Create Invoices in bill form (type ACCPAY) for that contact with the payout total and currency, a due date, and a line item referencing the payout period and payout id. Take the bill number Xero returns and write it back onto the Introw payout as the purchase order reference with Update a Payout. Show the bill number on the card and in the panel afterwards, and disable the button once a bill reference exists so nobody double-bills a partner.

A second button generates a single-use partner portal link with Create a Portal Session, using a visitor email the reviewer enters or picks from the partner record, so the reviewer can send the partner straight to their own view of the payout. Show the returned URL with a copy control and a note that it is single-use and short-lived. If the email is not authorised for the portal, Introw returns a 401, so show a plain message telling the reviewer to authorise that email in Introw first rather than a raw error.

Post each approval to a finance Slack channel with Send a Message: the partner, the payout total and currency, the period, the line count, who approved it, and the Xero bill number when one exists. The channel should be configurable in an app settings view.

Persist an activity trail in the app so the team can see who advanced a stage, who detached or declined a line and why, who raised the bill, and when each happened. Show it at the bottom of the detail panel. Introw does not carry that history, and it is the part the email threads were doing badly. Note that Introw amounts are decimal strings paired with ISO currency codes, so format them as money and never sum across currencies.