Recurly × HubSpot
How Recurly accounts, subscriptions, invoices and payments can give every HubSpot company a live revenue picture, and how a closed HubSpot deal can become a Recurly purchase.
Does Recurly integrate with HubSpot?
Recurly runs subscription billing: plans and add-ons, usage charges, recurring invoices, payment collection and dunning. HubSpot holds the customer relationship and the pipeline. This assessment shows how to connect the two so revenue and relationship data sit on the same record.
Public documentation. The client's own admin issues credentials, with no vendor approval needed.
Open API. Self-serve: the API is documented publicly, and keys are created in Recurly's admin console.
Based on the vendor's public documentation. Access terms are confirmed with the vendor and the client in discovery.
Recurly's documented REST API and JSON webhooks let HubSpot show what every customer pays, what they owe, and when they renew.
Campaign Creators assessment
HubSpot builds a Recurly data sync app that syncs Recurly accounts with HubSpot contacts, one way or two way, with default field mappings. Its listing states that it syncs customer data only, not subscriptions. It is the natural starting point for contact data. A custom build on Recurly's current REST API version and its webhooks adds subscription and invoice records, company-level MRR and ARR rollups, dunning status for customer success, usage, multiple sites and business entities, and write-back from HubSpot deals to Recurly purchases.
Ratings are CC judgments from Recurly's public API documentation. Plan features, limits and the scope of HubSpot's Recurly app are confirmed for the client's account during discovery.
Every billing change is a notification
Recurly sends documented webhook notifications for accounts, subscriptions, invoices, payments and dunning events, so HubSpot can follow billing within minutes.
MRR is calculated, not stored
Recurly subscriptions carry a price, quantity, add-ons and a billing interval, not an MRR field. The integration normalizes each subscription to a monthly value using rules finance signs off.
Agree the revenue definitions first
Finance signs off how MRR, ARR, churn and renewal dates are calculated, and which currency they report in, before any rollup is built.
Which Recurly APIs does the integration use?
Seven Recurly capabilities matter to a HubSpot build. Five carry the integration, one enriches it, and one is the starting point the build extends.
Accounts
/accounts · account codeThe billing account: account code, contact details, company, address, parent account and the default dunning campaign.
- Matched to HubSpot companies and contacts
codeis the client-defined account keyhas_past_due_invoiceandhas_active_subscriptionflags
Subscriptions, plans & add-ons
/subscriptions · /plans · add-onsEach subscription with its state, plan, add-ons, price, quantity, billing period and term dates.
state: active, canceled, expired, failed, future, pausedunit_amount,quantity,add_ons_total,subtotalcurrent_period_ends_at,current_term_ends_at,auto_renew
Invoices, payments & dunning
/invoices · transactions · dunning campaignsWhat each customer was billed, what they paid, what is past due and how far dunning has gone.
state: pending, processing, past_due, paid, failed, voidedtotal,balance,due_atdunning_events_sent,final_dunning_event
Webhooks
JSON or XML notifications, per endpointRecurly posts a notification for every change. JSON notifications are small (object type, event type, site and ID), so the integration reads the full record from the API before writing to HubSpot.
- subscription:
created,canceled,expired,renewed,paused - payment:
failed,succeeded; charge_invoice:past_due - dunning_event:
created
Purchases
/purchases · /purchases/preview · /purchases/pendingOne request creates or updates an account and adds subscriptions and one-time charges on a single invoice. A closed HubSpot deal can become a Recurly purchase.
- Deal line items → plan codes and line items
- Preview first, so sales sees the invoice total
- Business entity and collection method per purchase
Usage
/subscriptions/{id}/add_ons/{add_on_id}/usageUsage recorded against usage-based add-ons. Usage trends show expansion and risk signals on the HubSpot record.
- Needs usage-based add-ons set up in Recurly
amountandusage_timestampper record- Rolled up per period, not copied line by line
HubSpot's Recurly app
Built by HubSpot · data syncSyncs Recurly accounts with HubSpot contacts, one way or two way, with default field mappings and filters. The custom build extends what it covers.
- Customer data only, per the listing
- Custom field mappings need a paid Data Hub tier
- Field ownership is agreed between app and custom build
How does the Recurly HubSpot integration work?
Recurly webhooks reach a CC-hosted integration layer, which verifies each notification, reads the full record back from the API, computes revenue rollups and writes HubSpot records. HubSpot deals call back into Recurly to create purchases.
Recurly owns billing
Prices, invoices, payments and dunning run in Recurly. HubSpot stores them as reported and never recalculates a bill.
HubSpot owns the relationship
Companies, contacts, owners and the sales pipeline live in HubSpot. Recurly accounts link to them, not the other way round.
One writer per field
Where HubSpot's Recurly app already writes a contact field, the custom build leaves it alone. The split is written into the SOW.
What does Recurly HubSpot integration setup involve?
Each phase ends on a gate the client signs off before the next begins, so the fixed scope holds even if the account setup differs from the public docs.
Discovery & access
List the Recurly sites and business entities, the add-ons in use (fixed and usage-based), and whether HubSpot's Recurly app is installed and what it writes. Issue sandbox API keys.
Revenue definitions & ownership
Finance agrees how MRR, ARR, renewal date and churn are defined, how annual and multi-month plans are normalized, and which currency reports use. Agree which system and which app writes each field.
HubSpot data model
Create the Subscription and Invoice custom objects, company rollups, product properties, renewal pipeline and dunning ticket pipeline in a HubSpot sandbox.
Inbound build
Build the webhook endpoint, signature check, read-back, ordering rules, revenue engine and HubSpot writer against the Recurly sandbox site.
Write-back build
Build deal-to-purchase with a preview step, account creation from HubSpot, and validation against the synced plan catalog.
Backfill
Load accounts, live subscriptions, open invoices and an agreed history window through the list endpoints, then compute rollups once.
Parallel run & launch
Switch to the production site with workflows paused, run two weeks in parallel, then switch on dunning and renewal automations.
What does the Recurly HubSpot integration sync?
Attribute names follow Recurly's API reference for its current REST API version. Custom fields and the exact HubSpot objects for subscriptions and invoices are confirmed during discovery. Recurly returns amounts as decimals in the record's currency.
| Recurly field | HubSpot property | Object | Direction | Notes |
|---|---|---|---|---|
| Accounts → companies & contacts | ||||
| account.code + site | rc_account_code, rc_site | Company | RC → HS | Unique per site; both stored. |
| account.email | Contact | ↔ Both | Match key for the billing contact. | |
| account.first_name, last_name | firstname, lastname | Contact | ↔ Both | Fill blanks only; HubSpot edits stay in HubSpot. |
| account.company | name | Company | ↔ Both | Company created in HubSpot, then linked. |
| account.address | address, city, state, zip, country | Company | RC → HS | Country codes normalized to HubSpot values. |
| account.parent_account_id | Parent company association | Company | RC → HS | Recurly account hierarchy as parent and child companies. |
| account.has_past_due_invoice | rc_past_due | Company | RC → HS | Flag for lists and views. |
| Subscriptions → Subscription object & rollups | ||||
| subscription.id | rc_subscription_id | Subscription (custom object) | RC → HS | Unique key. |
| state | rc_state | Subscription (custom object) | RC → HS | active, canceled, expired, failed, future, paused. |
| plan.code, plan.name | rc_plan_code, rc_plan | Subscription (custom object) | RC → HS | Plan as a HubSpot product reference. |
| unit_amount, quantity, add_ons | Line items | Subscription (custom object) | RC → HS | Plan and add-ons with quantity. |
| subtotal ÷ plan interval | rc_mrr | Subscription (custom object) | RC → HS | Monthly value per the signed definition; computed in the integration layer. |
| current_term_ends_at, auto_renew | rc_renewal_date, rc_auto_renew | Subscription (custom object) | RC → HS | Feeds the renewal pipeline. |
| trial_ends_at | rc_trial_end | Subscription (custom object) | RC → HS | Trial conversion workflows. |
| canceled_at, expires_at, expiration_reason | rc_canceled_at, rc_expiration_reason | Subscription (custom object) | RC → HS | Churn reporting. |
| sum(rc_mrr) of active subscriptions | rc_company_mrr | Company | RC → HS | Computed in the integration layer. |
| rc_company_mrr × 12 | rc_company_arr | Company | RC → HS | Per the signed revenue definitions. |
| Invoices, payments & dunning | ||||
| invoice.number | rc_invoice_number | Invoice (custom object) | RC → HS | Unique per site. |
| state | rc_invoice_state | Invoice (custom object) | RC → HS | pending, processing, past_due, paid, failed, voided. |
| total, balance | rc_invoice_total, rc_balance | Invoice (custom object) | RC → HS | |
| due_at | rc_due_date | Invoice (custom object) | RC → HS | |
| dunning_events_sent, final_dunning_event | rc_dunning_stage | Company | RC → HS | Latest across open invoices. |
| payment failed notification | Task or Ticket | Ticket | RC → HS | Routed to the account owner or customer success. |
| Catalog, purchases & write-back | ||||
| plan and add-on codes | Product (hs_sku = plan or add-on code) | Product | RC → HS | Recurly owns the catalog. |
| HubSpot deal line items | POST /purchases | Deal | HS → RC | Purchase created for the linked account after a preview. |
| HubSpot company and contact | Recurly account (create) | Company | HS → RC | Only when a deal reaches the agreed stage. |
| subscription created notification | Deal stage: Closed won | Deal | RC → HS | Subscription associated to the deal. |
| Usage | ||||
| usage amount per add-on | rc_usage_current_period | Subscription (custom object) | RC → HS | Rolled up per billing period; usage-based add-ons only. |
How are authentication and API limits handled?
Recurly uses API keys; HubSpot uses one app token. Values Recurly does not publish are marked for confirmation.
| Topic | Recurly | HubSpot |
|---|---|---|
| Authentication | HTTP Basic with the API key as the username and an empty password. Sandbox and production sites have separate keys. A key with write access is used only where write-back is in scope. | Private app access token or OAuth 2.0 public app, scoped per object. |
| Base URL & versioning | https://v3.recurly.com, or https://v3.eu.recurly.com for EU sites. Every request names the API version in the Accept header; CC pins the current version rather than using latest. | One API domain for all portals. |
| Sites & entities | The /sites endpoint lists the sites a key can reach, and each notification carries its site_id. Business entities are set per account or purchase where the feature is enabled. Confirm key scope in discovery. | One portal; site and entity stored as properties. |
| Webhook security | HTTP Basic authentication on the endpoint, and a recurly-signature header on JSON notifications. Recurly advises confirming data through the API, so CC reads each record back before acting. | HubSpot signs its own webhooks with a v3 signature. |
| Delivery & retries | Failed deliveries are retried with growing intervals, up to ten attempts. Notifications are kept for 15 days in the Recurly admin console and can be retried in bulk. | Writes are immediate; batch endpoints handle volume. |
| Rate limits | Production: 1,000 requests per minute, counting GET requests only, over a sliding five-minute window. Sandbox: 400 requests per minute, all requests. Exceeding them returns HTTP 429. | Per-10-second burst and daily limits by subscription tier. |
| Plans & licensing | Usage-based add-ons, multiple business entities and credit invoices are site features. Confirm which are enabled in discovery. | Custom objects need an Enterprise hub; the Recurly app's custom field mappings need a paid Data Hub tier. |
What should you plan for, and what does the integration unlock?
Severity reflects impact on the SOW, not technical difficulty alone.
Challenges to plan for
Recurly reports price, quantity, add-ons and billing interval per subscription. Annual plans, ramps, discounts and usage all change the monthly figure, so finance signs off the formula before rollups are built.
Each subscription bills in its own currency. Finance picks a reporting currency and rate source before company rollups are built.
One deal per subscription, per renewal, or per expansion changes every report. Agree the pipeline design before backfill.
JSON notifications carry the object type, event type and ID, not the full record. Each one costs an API read, which counts against the GET limit during busy periods and backfills.
Account codes and invoice numbers are unique per site, not across sites. Every key is stored with its site, and catalogs are kept apart.
HubSpot's Recurly app can write contact fields both ways. The SOW lists which fields the app keeps and which the custom build owns.
Opportunities in HubSpot
MRR, ARR, active plans and next renewal sit on the company record, ready for lists, views and reports.
A failed payment or a past-due invoice opens a task or ticket for the owner, with the invoice attached, before the customer churns.
Renewal deals are created ahead of the term end, so account managers see every renewal in one pipeline.
Sales builds the deal in HubSpot, previews the Recurly invoice, and the closed deal creates the subscription.
Customers near a usage threshold enter an upsell list for their owner.
Cancellation dates and expiration reasons sit beside marketing source and owner, so leaders see why customers leave.
Start from the app, then extend.
HubSpot's Recurly app and the custom build share one HubSpot data model, so the work can be delivered in stages that each stand on their own.
- Confirm what HubSpot's Recurly app already syncs, and agree which contact fields it keeps.
- Add Subscription and Invoice records, and company MRR and ARR rollups, from webhooks.
- Add dunning, failed payments and renewals as HubSpot tasks, tickets and pipeline.
- Add deal-to-purchase write-back last, once the catalog and accounts are matched.
Which HubSpot properties does the integration create?
All custom properties use the rc_ prefix in a Recurly property group. Rollups are calculated in the integration layer so every report agrees.
| Internal name | Label | Object | Type | Source / logic |
|---|---|---|---|---|
| rc_account_code | Recurly Account Code | Company | Single-line text | account.code; unique with rc_site |
| rc_site | Recurly Site | Company | Dropdown | Site the account belongs to |
| rc_company_mrr | MRR | Company | Number (currency) | Sum of active subscription rc_mrr |
| rc_company_arr | ARR | Company | Number (currency) | MRR × 12, per signed definition |
| rc_active_subscriptions | Active Subscriptions | Company | Number | Count of active subscriptions |
| rc_next_renewal_date | Next Renewal | Company | Date | Earliest current_term_ends_at |
| rc_past_due | Has Past-Due Invoice | Company | Single checkbox | account.has_past_due_invoice |
| rc_balance_due | Balance Due | Company | Number (currency) | Sum of open invoice balance |
| rc_subscription_id | Recurly Subscription ID | Subscription | Single-line text | subscription.id; unique |
| rc_state | Subscription State | Subscription | Dropdown | subscription.state |
| rc_mrr | Subscription MRR | Subscription | Number (currency) | subtotal normalized to one month |
| rc_invoice_number | Recurly Invoice Number | Invoice | Single-line text | invoice.number; unique with rc_site |
Interactive scope builder
Choose the modules and fields for this engagement and the direction each one syncs. Required fields are the keys the integration cannot run without. Copy the summary into the SOW or a reply to the client.
Scope summary
Sources & verification
Based on public documentation. Each item marked for confirmation is verified against the client's Recurly sites during discovery.
Recurly HubSpot integration FAQ
Does Recurly integrate with HubSpot?
Yes. HubSpot's Recurly app syncs Recurly accounts with HubSpot contacts, and is the starting point for contact data. Campaign Creators extends it with a custom build on Recurly's REST API and webhooks for subscriptions, invoices, revenue rollups, dunning and write-back.
What data syncs between Recurly and HubSpot?
Recurly accounts match to HubSpot companies and contacts, and subscriptions and invoices sync with their state, plan, amounts and dates. MRR, ARR, renewal dates and dunning status roll up to the company. A closed HubSpot deal can become a Recurly purchase.
Which system owns which data?
Recurly owns billing: plans, subscriptions, invoices, payments and dunning. HubSpot owns the customer relationship and the pipeline. Finance signs off how MRR, ARR, churn and renewal dates are calculated, and the integration applies those rules to every rollup.
What does setting up the Recurly HubSpot integration involve?
Seven phases, each closed by a client sign-off: discovery and access, revenue definitions and ownership, the HubSpot data model, the inbound build, the write-back build, a backfill, and a parallel run before workflows are switched on.
How long does the integration take and what does it cost?
Timeline and cost depend on the Recurly sites and business entities in scope, the history to load, and whether deal-to-purchase write-back is included. Campaign Creators confirms these in discovery and provides a fixed scope before the build starts.
Ready to Get More From HubSpot?
Whether you’re implementing HubSpot, optimizing what you already have, connecting systems, or scaling your customer experience, we’ll help you figure out the right next step.
.png?width=1920&height=553&name=cc-logo-color%20(2024).png)