Developer Handover Pack

Developer Handover Pack

Subscription & Recurring Billing

Handles subscriber retrieval, invoice creation, and payment charging at the start of each billing cycle. The agent reads all active subscription records from HubSpot, maps each record to the correct Xero account code and tax treatment based on plan tier, generates a Xero invoice for every subscriber, and triggers a Stripe charge against the stored payment method. It captures the charge outcome (success or failure) for every invoice and passes that payload downstream. This agent must complete atomically per subscriber: if invoice creation in Xero fails for a given record, the Stripe charge for that subscriber must not fire. Estimated build time: 14 hours. Complexity: Moderate.

// Input
HubSpot query filter: { lifecyclestage: 'customer', hs_lead_status: 'active', billing_cycle_date: TODAY }
Fields consumed: contact_id, email, first_name, last_name, plan_tier, plan_price_usd, stripe_customer_id, xero_contact_id, renewal_date

// Output
Per subscriber: { subscriber_id, xero_invoice_id, stripe_payment_intent_id, charge_status: 'succeeded'|'failed', amount_usd, currency: 'USD', timestamp_utc }
Batch summary: { total_invoices_created, total_charged, total_failed, billing_run_id }

Monitors Stripe for failed payment events, sends recovery emails via Gmail, schedules retry attempts at a fixed 72-hour interval, and updates subscriber status in HubSpot after each attempt outcome. The agent is event-driven: it activates on receipt of a Stripe payment_intent.payment_failed webhook rather than on a schedule. It maintains a retry counter per subscriber and stops automated retries after two attempts (72 hours and 144 hours post-failure), at which point the subscriber record is flagged in HubSpot for manual escalation and no further automated emails are sent. Estimated build time: 12 hours. Complexity: Moderate.

// Input
Stripe webhook payload: { type: 'payment_intent.payment_failed', data.object: { id: payment_intent_id, customer: stripe_customer_id, amount: int, currency: 'usd', last_payment_error: { code, message } } }
Lookup: HubSpot contact by stripe_customer_id -> { contact_id, email, first_name, plan_tier, retry_count, xero_invoice_id }

// Output (attempt 1 and attempt 2)
Gmail: recovery email sent to subscriber email with card-update link and personalised greeting
Stripe: PaymentIntent retry scheduled at T+72h and T+144h via the automation platform's delay node
HubSpot contact updated: { billing_status: 'payment_failed', retry_count: N, last_retry_attempt_utc: timestamp }

// On max retries exceeded
HubSpot contact updated: { billing_status: 'escalated', retry_count: 2 }
No further automated emails sent; record surfaced in finance team review queue

Matches Stripe payment confirmations to open Xero invoices, marks them as paid, sends payment confirmation emails to successful payers, queues renewal reminder emails for subscribers approaching their renewal date, and posts the billing run summary to the designated Slack finance channel. This agent handles both the initial successful payment path (triggered immediately after the Billing Cycle Agent) and the successful retry path (triggered when the Failed Payment Recovery Agent's retry clears). Unmatched items, where no open Xero invoice can be found for a given Stripe payment, are flagged in a Supabase exceptions table and surfaced to the bookkeeper (Owen Fischer) for manual review. Estimated build time: 12 hours. Complexity: Moderate.

// Input
Stripe webhook payload: { type: 'payment_intent.succeeded', data.object: { id: payment_intent_id, customer: stripe_customer_id, amount_received: int, currency: 'usd' } }
Xero lookup: open invoice where Contact.ContactID = xero_contact_id AND Status = 'AUTHORISED' AND AmountDue = (amount_received / 100)
HubSpot lookup by stripe_customer_id: { contact_id, email, first_name, renewal_date, plan_tier }

// Output
Xero: invoice Status set to 'PAID', payment record created with { Date: today, Amount: amount_received_usd, Account: bank_account_id }
Gmail: confirmation email sent to subscriber email with invoice PDF link and payment amount
Gmail (conditional): renewal reminder email queued if renewal_date is within 30 days
Slack: message posted to #finance-billing channel: { billing_run_id, total_invoices, total_paid_usd, total_failed, retry_successes, unmatched_count }

// On unmatched invoice
Supabase exceptions table insert: { payment_intent_id, stripe_customer_id, amount_usd, error: 'no_matching_xero_invoice', flagged_at_utc: timestamp }
Slack alert posted to #finance-billing: 'Unmatched payment flagged for review: [stripe_customer_id]'

// ============================================================
// TRIGGER
// ============================================================
SCHEDULE: cron(0 6 1 * *)  // 06:00 UTC on billing period start date
  -> billing_run_id = uuid()
  -> date_today = ISO8601 date

// ============================================================
// BILLING CYCLE AGENT
// ============================================================
HUBSPOT_QUERY:
  endpoint: GET /crm/v3/objects/contacts/search
  filter: { lifecyclestage = 'customer', hs_lead_status = 'active', billing_cycle_date = date_today }
  fields_returned: [contact_id, email, first_name, last_name, plan_tier,
                    plan_price_usd, stripe_customer_id, xero_contact_id, renewal_date]
  -> subscriber_list[]

FOR EACH subscriber IN subscriber_list:

  // Dedupe check
  XERO_CHECK:
    endpoint: GET /api.xro/2.0/Invoices
    filter: ContactID = subscriber.xero_contact_id AND Date = date_today AND Status = 'DRAFT'|'AUTHORISED'
    IF existing_invoice FOUND -> UPDATE existing_invoice
    ELSE -> CREATE new invoice

  XERO_CREATE_INVOICE:
    endpoint: POST /api.xro/2.0/Invoices
    body: { Type: 'ACCREC', Contact: { ContactID: subscriber.xero_contact_id },
            Date: date_today, DueDate: date_today,
            LineItems: [{ Description: subscriber.plan_tier, UnitAmount: subscriber.plan_price_usd,
                          AccountCode: '200'|'201', TaxType: 'OUTPUT' }],
            Status: 'AUTHORISED' }
    -> xero_invoice_id, xero_invoice_url

  STRIPE_CHARGE:
    endpoint: POST /v1/payment_intents
    body: { amount: subscriber.plan_price_usd * 100, currency: 'usd',
            customer: subscriber.stripe_customer_id,
            payment_method: default_payment_method,
            confirm: true, off_session: true,
            metadata: { xero_invoice_id: xero_invoice_id, billing_run_id: billing_run_id } }
    -> payment_intent_id, charge_status ('succeeded'|'requires_payment_method'|'failed')

// ============================================================
// DECISION: charge_status
// ============================================================
IF charge_status = 'succeeded':
  -> EMIT payment_intent.succeeded -> Reconciliation and Notification Agent

IF charge_status = 'failed' OR 'requires_payment_method':
  -> EMIT payment_intent.payment_failed -> Failed Payment Recovery Agent

// ============================================================
// FAILED PAYMENT RECOVERY AGENT
// ============================================================
ON_EVENT: payment_intent.payment_failed
  stripe_payload: { payment_intent_id, stripe_customer_id, amount, last_payment_error.code }

  HUBSPOT_LOOKUP:
    endpoint: GET /crm/v3/objects/contacts?filter=stripe_customer_id={stripe_customer_id}
    -> contact_id, email, first_name, plan_tier, retry_count, xero_invoice_id

  GMAIL_SEND (attempt 1 email):
    to: subscriber.email
    subject: 'Action required: payment for your [YourCompany.com] subscription'
    body_fields: [first_name, plan_tier, amount_usd, card_update_url]
    -> message_id

  HUBSPOT_UPDATE:
    endpoint: PATCH /crm/v3/objects/contacts/{contact_id}
    body: { billing_status: 'payment_failed', retry_count: 1,
            last_retry_attempt_utc: timestamp_utc }

  DELAY: 72 hours

  STRIPE_RETRY:
    endpoint: POST /v1/payment_intents/{payment_intent_id}/confirm
    -> charge_status

  IF charge_status = 'succeeded': -> EMIT payment_intent.succeeded -> Reconciliation Agent
  IF charge_status = 'failed' AND retry_count < 2:
    GMAIL_SEND (attempt 2 email): same template, updated tone
    HUBSPOT_UPDATE: { retry_count: 2 }
    DELAY: 72 hours
    STRIPE_RETRY (attempt 2) -> charge_status
    IF 'succeeded': -> EMIT payment_intent.succeeded -> Reconciliation Agent
    IF 'failed': HUBSPOT_UPDATE { billing_status: 'escalated' } // no further automated action

// ============================================================
// RECONCILIATION AND NOTIFICATION AGENT
// ============================================================
ON_EVENT: payment_intent.succeeded
  stripe_payload: { payment_intent_id, stripe_customer_id, amount_received, metadata.xero_invoice_id, metadata.billing_run_id }

  XERO_MATCH:
    endpoint: GET /api.xro/2.0/Invoices/{xero_invoice_id}
    validate: Status = 'AUTHORISED' AND AmountDue = amount_received / 100
    IF match: PROCEED
    IF no match: INSERT exceptions table { payment_intent_id, stripe_customer_id, amount_usd, error: 'no_matching_xero_invoice' }
               POST Slack alert -> HALT for this subscriber

  XERO_MARK_PAID:
    endpoint: PUT /api.xro/2.0/Invoices/{xero_invoice_id}/Payments
    body: { Date: date_today, Amount: amount_received_usd, Account: { Code: 'STRIPE-BANK' } }
    -> xero_payment_id, xero_invoice_url (OnlineInvoiceUrl)

  HUBSPOT_LOOKUP: stripe_customer_id -> { contact_id, email, first_name, renewal_date, billing_status }

  GMAIL_SEND (confirmation):
    to: subscriber.email
    body_fields: [first_name, amount_usd, date_today, xero_invoice_url]

  IF renewal_date <= date_today + 30 days AND billing_status = 'active':
    GMAIL_SEND (renewal reminder):
      to: subscriber.email
      body_fields: [first_name, renewal_date, plan_tier]

  HUBSPOT_UPDATE: { billing_status: 'active', retry_count: 0 }

  SUPABASE_UPSERT billing_run_summary:
    { billing_run_id, total_paid_count++, total_paid_usd += amount_received_usd }

  // After all events processed or timeout reached:
  SLACK_POST:
    channel: '#finance-billing'
    fields: [billing_run_id, total_invoices_created, total_paid_usd, total_failed_count,
             retry_success_count, unmatched_count]