Integration and API Spec

Integration and API Spec

Vendor and Subscription Renewal Tracking

Google Sheets is the master subscription register. The Renewal Triage Agent reads all active rows on each scheduled run. The Finance Record Agent writes the confirmed decision, decision date, and acting owner back to the corresponding row. A service account with domain-wide delegation is the preferred auth pattern to avoid token expiry disrupting the daily 7:00 AM trigger.

// Read input
Spreadsheet ID: ${GSHEETS_REGISTER_ID}
Range: ${GSHEETS_TAB_NAME}!A1:Z500
// Read output
Array of row objects keyed by column header
// Write input (decision update)
Row index, decision, decision_date, decision_owner
// Write output
Updated row confirmation (HTTP 200)

Notion stores the canonical vendor contract page for each supplier. The Renewal Triage Agent queries the vendor database to enrich triage output with contract metadata. After a decision is confirmed, the automation updates the relevant vendor page with the new renewal date, confirmed cost, and decision taken.

// Query input
Database ID: ${NOTION_VENDOR_DB_ID}
Filter: { property: 'Vendor Name', title: { equals: vendor_name } }
// Query output
Page ID, Renewal Date, Annual Cost, Last Decision
// Update input
Page ID, Renewal Date (new), Annual Cost (confirmed), Last Decision, Last Updated
// Update output
Updated page object (HTTP 200)

Slack is used by Agent 2 (Stakeholder Notification Agent) to post a structured renewal alert to each contract owner. Messages are sent as direct messages or to a designated channel using the contract_owner_slack_id field from the Google Sheets register. Each message contains vendor name, renewal date, annual cost, notice deadline, and a prompt to log a decision.

// Input per contract owner
channel: U0XXXXXXXXX (Slack member ID from register)
blocks: [ Header, Section (vendor, date, cost, notice deadline), Actions (link to register) ]
text: 'Renewal alert: {vendor_name} renews on {renewal_date}'
// Output
{ ok: true, ts: '...', channel: '...' } on success
{ ok: false, error: 'channel_not_found' } on failure -> route to fallback channel

Gmail is used by Agent 2 (Stakeholder Notification Agent) to send a consolidated upcoming-charges summary to the finance contact. The email lists all renewals due within 30 days, with vendor names, amounts, and due dates, plus a link to the live Google Sheets register. The sender identity must be the IT manager or a shared mailbox — not the automation platform's own email address.

// Input
to: ${GMAIL_FINANCE_RECIPIENT}
from: ${GMAIL_SENDER_ADDRESS}
subject: 'Upcoming Renewals Summary - {run_date}'
body_html: rendered HTML from template with {{renewal_table}}, {{register_link}}
// Output
{ id: 'message_id', threadId: '...', labelIds: ['SENT'] } on success
HTTP 403 invalid_grant -> refresh token expired -> alert via fallback Slack channel

Xero is used by Agent 3 (Finance Record Agent) to create a draft bill for each confirmed renewal. The bill is pre-populated with the vendor name (matched to an existing supplier contact), the renewal amount, and the due date. The bill is created in draft status only — the finance officer must approve and post it manually. Xero is not used for any read operations in this automation.

// Contact lookup input
GET /api.xro/2.0/Contacts?where=Name=="{vendor_name}"
Headers: Authorization: Bearer {access_token}, Xero-tenant-id: ${XERO_TENANT_ID}
// Contact lookup output
ContactID (UUID) for matched supplier
// Bill creation input
POST /api.xro/2.0/Invoices
{ Type: 'ACCPAY', Contact: { ContactID }, Date: run_date, DueDate: renewal_date,
  Status: 'DRAFT', LineItems: [{ Description: vendor_name + ' renewal',
  UnitAmount: annual_cost, AccountCode: ${XERO_EXPENSE_ACCOUNT_CODE},
  TaxType: ${XERO_TAX_TYPE} }] }
// Bill creation output
{ Invoices: [{ InvoiceID, Status: 'DRAFT', InvoiceNumber }] }

// Credential store: full key inventory
// Google Sheets
GSHEETS_REGISTER_ID         = '<spreadsheet_id>'
GSHEETS_TAB_NAME            = '<sheet_tab_name>'
GSHEETS_SERVICE_ACCOUNT_KEY = '<base64_encoded_service_account_json>'

// Gmail
GMAIL_CLIENT_ID             = '<google_oauth_client_id>'
GMAIL_CLIENT_SECRET         = '<google_oauth_client_secret>'
GMAIL_REFRESH_TOKEN         = '<offline_refresh_token>'
GMAIL_SENDER_ADDRESS        = '<sender@yourcompany.com>'
GMAIL_FINANCE_RECIPIENT     = '<finance@yourcompany.com>'

// Slack
SLACK_BOT_TOKEN             = 'xoxb-...'
SLACK_FALLBACK_CHANNEL      = '<channel_id_C0XXXXXXXXX>'

// Xero
XERO_CLIENT_ID              = '<xero_oauth_client_id>'
XERO_CLIENT_SECRET          = '<xero_oauth_client_secret>'
XERO_REFRESH_TOKEN          = '<xero_refresh_token>'
XERO_TENANT_ID              = '<xero_organisation_tenant_id>'
XERO_EXPENSE_ACCOUNT_CODE   = '429'
XERO_TAX_TYPE               = 'NONE'

// Notion
NOTION_INTEGRATION_TOKEN    = 'secret_...'
NOTION_VENDOR_DB_ID         = '<notion_database_id>'

// Orchestration
WEBHOOK_SHARED_SECRET       = '<random_32_byte_hex_string>'
AUTOMATION_TIMEZONE         = 'America/New_York'
REGISTER_LINK               = '<public_or_shared_link_to_google_sheet>'