Integration and API Spec

Integration and API Spec

Commission and Payout Calculation

Used by the Deal Ingestion Agent (Agent 1) to retrieve all closed-won deals within the pay period date range. Connection is polled on a schedule aligned to pay period close; no inbound webhook from HubSpot is required.

// Input
period_start: ISO 8601 date string
period_end:   ISO 8601 date string
// Output
deals[]: { deal_id, deal_name, amount, close_date, owner_id, pipeline_id, dealstage, product_line, split_flag }

Used by both the Deal Ingestion Agent (Agent 1) and the Commission Calculation Agent (Agent 2). Agent 1 writes the cleaned deal list. Agent 2 reads the commission rate table and writes the per-rep payout summary. Two named sheets must exist in the designated spreadsheet.

// Input (Agent 2 reads)
sheet: 'deal_list'  -> deal records written by Agent 1
sheet: 'rate_table' -> rep_id, tier_label, attainment_min_pct, attainment_max_pct, commission_rate_pct
// Output (Agent 2 writes)
sheet: 'payout_summary' -> rep_id, rep_name, deal_count, total_revenue, tier_applied, gross_commission, period_label

Used by the Payout Distribution Agent (Agent 3) for two distinct functions: posting an interactive approval message to the manager, and sending personalised direct messages to each rep after approval. A single Slack Bot App with the required scopes handles both.

// Outbound (approval message)
POST chat.postMessage -> channel: SLACK_MANAGER_USER_ID
  payload: { period_label, rep_count, total_payout_usd, blocks: [approval_table, approve_btn, flag_btn] }
// Inbound (interaction callback)
POST <interaction_endpoint> -> { action_id, payload_id, user_id, ts }
// Outbound (rep DM)
POST chat.postMessage -> channel: rep_slack_user_id
  payload: { period_label, deals[], rate_applied, gross_commission }

Used by the Payout Distribution Agent (Agent 3) to push each rep's approved commission total as an additional earnings line item for the current pay run. Connection requires Gusto API access to be enabled on the account by Gusto support before credentials can be provisioned.

// Input
approved_payouts[]: { hubspot_owner_id, rep_name, gross_commission_usd }
// Lookup
GUSTO_EMPLOYEE_ID_MAP: { hubspot_owner_id -> gusto_employee_id }
// API call
PUT /v1/companies/{GUSTO_COMPANY_ID}/payrolls/{payroll_id}
  body: { employee_compensations: [{ employee_id, additional_earnings: [{ earning_type_id, amount }] }] }

Used by the Payout Distribution Agent (Agent 3) to create a commission expense journal entry after payouts are approved and pushed to Gusto. The journal entry codes the total commission expense to the correct cost centre and attaches the approved payout summary as a supporting document.

// Input
total_commission_usd: number
period_label: string
payout_sheet_url: string
// API call
POST /api.xro/2.0/ManualJournals
  body: { Narration, Date, JournalLines: [
    { LineAmount: +total, AccountCode: XERO_COMMISSION_EXPENSE_CODE, TaxType, Tracking },
    { LineAmount: -total, AccountCode: XERO_PAYROLL_LIABILITY_CODE, TaxType }
  ] }

// Credential store manifest — namespace: commission-payout
// All entries are secret-type unless marked [config]

HUBSPOT_API_TOKEN                  // HubSpot Private App token
HUBSPOT_PIPELINE_ID                // [config] HubSpot deal pipeline ID
HUBSPOT_CLOSEDWON_STAGE_ID         // [config] HubSpot closed-won stage ID

GOOGLE_SERVICE_ACCOUNT_JSON        // Full JSON key for Google service account
SHEETS_COMMISSION_SPREADSHEET_ID   // [config] Target spreadsheet ID

SLACK_BOT_TOKEN                    // Slack Bot User OAuth Token (xoxb-...)
SLACK_SIGNING_SECRET               // Slack App signing secret for payload validation
SLACK_MANAGER_USER_ID              // [config] Slack user ID of approving manager
SLACK_USER_ID_MAP                  // [config] JSON: { hubspot_owner_id: slack_user_id }

GUSTO_CLIENT_ID                    // Gusto OAuth client ID
GUSTO_CLIENT_SECRET                // Gusto OAuth client secret
GUSTO_ACCESS_TOKEN                 // Gusto access token (refreshed before each run)
GUSTO_REFRESH_TOKEN                // Gusto refresh token
GUSTO_COMPANY_ID                   // [config] Gusto company UUID
GUSTO_EMPLOYEE_ID_MAP              // [config] JSON: { hubspot_owner_id: gusto_employee_id }
GUSTO_COMMISSION_EARNING_TYPE_ID   // [config] Gusto earning type code for commissions

XERO_CLIENT_ID                     // Xero OAuth client ID
XERO_CLIENT_SECRET                 // Xero OAuth client secret
XERO_ACCESS_TOKEN                  // Xero access token (refreshed before each run)
XERO_REFRESH_TOKEN                 // Xero refresh token
XERO_TENANT_ID                     // [config] Xero organisation tenant ID
XERO_COMMISSION_EXPENSE_CODE       // [config] Xero account code: commission expense
XERO_PAYROLL_LIABILITY_CODE        // [config] Xero account code: payroll liability
XERO_TRACKING_CATEGORY_ID          // [config] Xero tracking category ID for cost centre
XERO_TAX_TYPE                      // [config] Xero tax type string (e.g. NONE)