Developer Handover Pack

Developer Handover Pack

Receivables & Invoice Chasing

Watches every open invoice in Xero and stages a prioritised reminder sequence based on how overdue each invoice is. Replaces manual steps 1 and 2: pulling the aged receivables report and deciding who to chase. Nothing slips through because the agent evaluates all open balances on a scheduled poll rather than relying on a person to remember.

// Input
Xero invoice object {
  invoice_id: string,
  contact_id: string,
  due_date: date,
  amount_due: float,
  status: 'AUTHORISED' | 'PARTIAL',
  days_overdue: integer
}

// Processing
IF days_overdue IN [1, 7, 14, 30] AND account_flagged == false
  -> stage reminder at priority tier (LOW | MEDIUM | HIGH | ESCALATE)
  -> write scheduled_send_time to FullSpec queue
ELSE
  -> skip or log for human review

// Output
Prioritised chase queue entry {
  invoice_id: string,
  contact_email: string,
  reminder_tier: 'LOW' | 'MEDIUM' | 'HIGH' | 'ESCALATE',
  scheduled_send_time: ISO8601,
  stripe_pay_link: string (generated next stage)
}

Picks up staged reminders from the queue and sends each one via Gmail with the invoice PDF attached and a Stripe pay link embedded. Logs every send automatically in FullSpec Automation. Replaces manual steps 3 and 4: writing reminder emails by hand and logging sends in a spreadsheet. Email content is templated by reminder tier so tone scales with urgency.

// Input
Queue entry {
  invoice_id: string,
  contact_email: string,
  contact_name: string,
  amount_due: float,
  currency: string,
  reminder_tier: 'LOW' | 'MEDIUM' | 'HIGH' | 'ESCALATE',
  invoice_pdf_url: string
}

// Processing
1. Fetch email template for reminder_tier
2. Generate Stripe Checkout Session -> pay_link URL
3. Compose email: merge contact_name, amount_due, pay_link, invoice_pdf_url
4. Gmail.send(to: contact_email, subject, body, attachment: invoice_pdf)
5. Log send event to FullSpec activity log

// Output
Send record {
  invoice_id: string,
  sent_at: ISO8601,
  recipient: string,
  reminder_tier: string,
  pay_link: string,
  send_status: 'success' | 'failed',
  retry_count: integer
}

Listens for incoming payments in Xero and matches each one to the correct open invoice, including partial amounts. Marks invoices reconciled, updates their status in Xero, and pushes a team notification via FullSpec Automation. Replaces manual step 6. A short tuning period against real payment data is expected before partial-match confidence stabilises.

// Input (Xero payment event or Stripe webhook)
Payment event {
  payment_id: string,
  invoice_id: string,
  amount_paid: float,
  currency: string,
  payment_date: date,
  source: 'stripe' | 'bank_feed' | 'manual'
}

// Processing
IF amount_paid >= amount_due
  -> Xero.Payments.create(invoiceID, amount, status: PAID)
  -> Remove invoice from chase queue
  -> Notify team via FullSpec
ELSE IF amount_paid > 0 AND amount_paid < amount_due
  -> Record partial payment in Xero
  -> Reschedule chase reminder for remaining balance
  -> Notify team of partial receipt
ELSE
  -> Flag payment as unmatched -> human review queue

// Output
Reconciliation record {
  invoice_id: string,
  xero_status: 'PAID' | 'PARTIAL' | 'UNMATCHED',
  reconciled_at: ISO8601,
  remaining_balance: float,
  notification_sent: boolean
}

// ─── TRIGGER ────────────────────────────────────────────────────────────────
SOURCE: Xero invoice webhook OR scheduled poll (every 15 min)
EVENT:  invoice.due_date < today AND invoice.amount_due > 0
        invoice.status IN ['AUTHORISED', 'PARTIAL']

// ─── STAGE 1: Chase Scheduler Agent ─────────────────────────────────────────
INPUT:  { invoice_id, contact_id, contact_email, contact_name,
          due_date, amount_due, currency, days_overdue }

RULE:   days_overdue == 1   -> tier = 'LOW',      send_delay = +0h
        days_overdue == 7   -> tier = 'MEDIUM',   send_delay = +0h
        days_overdue == 14  -> tier = 'HIGH',     send_delay = +0h
        days_overdue >= 30  -> tier = 'ESCALATE', send_delay = +0h
        account_flagged_sensitive == true -> SKIP, log to human review

WRITE:  FullSpec queue entry {
          invoice_id, contact_email, contact_name,
          reminder_tier, scheduled_send_time, amount_due, currency,
          invoice_pdf_url (fetched from Xero Files API)
        }

// ─── STAGE 2: Reminder Sender Agent ─────────────────────────────────────────
TRIGGER: queue entry.scheduled_send_time == now()

ACTION 1: Stripe.checkout.sessions.create({
            amount: amount_due * 100,  // cents
            currency: currency,
            metadata: { invoice_id }
          }) -> pay_link URL

ACTION 2: Load email template for reminder_tier
          Merge: { contact_name, amount_due, pay_link, invoice_pdf_url }

ACTION 3: Gmail.messages.send({
            to: contact_email,
            subject: 'Invoice [invoice_id] - Payment reminder',
            body: rendered_template,
            attachment: invoice_pdf_url
          })

ACTION 4: FullSpec.log({
            invoice_id, sent_at, recipient, reminder_tier,
            pay_link, send_status, retry_count
          })

ON FAILURE: retry x2, then -> human review queue

// ─── DECISION: Client reply detected? ───────────────────────────────────────
IF Gmail inbound reply detected on watched thread:
  -> Route thread to bookkeeper inbox label 'Chase - Reply'
  -> PAUSE automation for this invoice_id pending human action
  -> [HUMAN HANDOFF: Bookkeeper handles reply, promise to pay, or dispute]

// ─── STAGE 3: Payment Reconciliation Agent ───────────────────────────────────
TRIGGER A: Stripe webhook  payment.succeeded { payment_intent_id, amount, metadata.invoice_id }
TRIGGER B: Xero bank feed  payment detected against open invoice

MATCH LOGIC:
  amount_paid >= amount_due:
    -> Xero.Payments.create({ InvoiceID, Amount, Date, Account })
    -> invoice.status = 'PAID'
    -> Remove invoice_id from chase queue
    -> FullSpec.notify(team, 'Invoice [invoice_id] paid in full')

  0 < amount_paid < amount_due:
    -> Record partial in Xero
    -> invoice.status = 'PARTIAL'
    -> Recalculate remaining_balance
    -> Re-queue chase reminder for remaining_balance at current tier
    -> FullSpec.notify(team, 'Partial payment received for [invoice_id]')

  No match found:
    -> Log unmatched payment -> human review queue
    -> [HUMAN HANDOFF: Bookkeeper investigates]

// ─── OUTPUT ─────────────────────────────────────────────────────────────────
RESULT:  Invoice marked PAID in Xero
         Chase queue entry removed
         Reconciliation record written to FullSpec activity log
         Team notification dispatched
         [HUMAN HANDOFF for disputes and escalations only]