HubSpot App

The LostChurn HubSpot App syncs recovery data into your HubSpot CRM automatically. Contacts get custom recovery properties, successful recoveries create deals, and every recovery event appears on the contact timeline.

What You Get

After installation:

• Contact Properties -- Custom properties added to every contact: lostchurn_mrr, lostchurn_recovery_count, lostchurn_churn_risk, and lostchurn_customer_id.
• Deal Properties -- Recovery-specific properties on deals: recovery status, decline code, and retry count.
• Revenue Recovery Pipeline -- A dedicated deal pipeline with stages matching the recovery lifecycle (In Progress, Closed Won, Closed Lost).
• Timeline Events -- Visual recovery history on each contact's timeline showing campaign starts, emails sent, retries attempted, and outcomes.
• Real-Time Sync -- Updates push to HubSpot within seconds of events occurring in LostChurn.

Install from the HubSpot Marketplace

1. Visit the LostChurn app on the HubSpot Marketplace.
2. Click Install app.
3. Sign in to HubSpot if prompted.
4. Review the requested OAuth scopes:
   • crm.objects.contacts.read and crm.objects.contacts.write -- create and update contacts
   • crm.objects.deals.read and crm.objects.deals.write -- create recovery deals
   • timeline -- log recovery events on contact timelines
5. Click Grant access to authorize.
6. You are redirected back to LostChurn with your HubSpot portal ID confirmed.

Prerequisites

• A HubSpot account with Marketing Hub or Sales Hub (Starter plan or above)
• Admin access to your HubSpot portal
• A LostChurn account with at least one active payment processor connected

How the Sync Works

Contacts

Contacts are matched by email address and upserted (created if new, updated if existing).

Custom properties are created automatically when you first connect.

Deals

When a recovery succeeds, a Deal is created in the Revenue Recovery pipeline:

• Deal name: Recovery - {customer_email} - {date}
• Amount: The recovered payment amount
• Stage progression:
  • Recovery Started -- In Progress
  • Retry Attempted -- In Progress
  • Recovery Succeeded -- Closed Won
  • Recovery Exhausted -- Closed Lost

Timeline Events

Key recovery events appear as visual entries on the contact timeline:

• Recovery campaign started
• Email or SMS sent (with template name)
• Payment retry attempted (with result)
• Recovery succeeded or failed
• Customer updated payment method

Timeline events are created using HubSpot's Timeline Events API and appear alongside other CRM activity.

Webhook Receiver

The LostChurn HubSpot App includes a webhook endpoint that receives outbound events from LostChurn. When a recovery event occurs:

1. LostChurn sends the event to the HubSpot App's webhook handler.
2. The handler verifies the webhook signature using HMAC-SHA256.
3. The contact is upserted in HubSpot with updated recovery properties.
4. If the recovery succeeded, a deal is created in the Revenue Recovery pipeline.
5. A timeline event is logged on the contact record.

Sync Behavior

• Real-time: Events push to HubSpot within seconds of occurring in LostChurn.
• Batch sync: Trigger a full sync from Settings > CRM > HubSpot > Re-sync All. Records are processed in batches of 100.
• Conflict resolution: Recovery fields (MRR, recovery count, churn risk) -- LostChurn wins. Sales fields (lifecycle stage, deal owner) -- HubSpot wins. Contact fields (name, phone) -- most recently updated wins.

Troubleshooting

Contact not syncing

• Verify the customer has a valid email address in LostChurn.
• Check Settings > CRM > HubSpot > Sync Log for error details.
• Ensure your HubSpot plan allows the required number of contacts.

Deal not created

• Confirm the "Revenue Recovery" pipeline exists in HubSpot. LostChurn creates it automatically, but it may have been deleted.
• Partial recoveries do not create deals by default. Only fully succeeded recoveries generate deals.

Timeline events missing

• Verify the timeline scope was granted during OAuth authorization.
• Check the sync log for timeline API errors. HubSpot rate limits timeline event creation.

OAuth token expired

LostChurn refreshes tokens automatically every 6 hours. If you see an authentication error:

1. Go to Settings > CRM > HubSpot in LostChurn.
2. Click Reconnect.
3. Complete the OAuth flow again.

Disconnecting

1. Go to Settings > CRM > HubSpot in LostChurn.
2. Click Disconnect.
3. Choose whether to keep or delete LostChurn custom properties in HubSpot.

Existing data in HubSpot is preserved unless you explicitly remove custom properties.

Next Steps

• Salesforce integration -- alternative CRM integration
• CRM sync settings -- configure sync behavior and field mapping
• Zapier integration -- connect LostChurn to 6,000+ apps