Integration Products | Campaign Creators

HubSpot <> Recurly Integration

Written by Admin | Nov 19, 2026, 6:04:22 AM
Integration Assessment
Integration Assessment · Subscription Billing

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.

REST API (v3)JSON webhooksPlans, add-ons and usageInvoices and dunningPurchases write-backHubSpot's Recurly app
Platform ownerRecurly
Integration typeHubSpot app plus custom build
Primary directionRecurly → HubSpot
FeasibilityStrong fit
API accessOpen API
01 — Summary

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.

API access
Open APIOpen with conditionsGated API

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.

Scorecard
Data richnessHigh
API accessSelf-serve
Public docsExtensive
Build complexityModerate

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.

Strength

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.

Plan for

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.

Gate

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.

02 — API modules

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.

Core

Accounts

/accounts · account code

The billing account: account code, contact details, company, address, parent account and the default dunning campaign.

  • Matched to HubSpot companies and contacts
  • code is the client-defined account key
  • has_past_due_invoice and has_active_subscription flags
Core

Subscriptions, plans & add-ons

/subscriptions · /plans · add-ons

Each subscription with its state, plan, add-ons, price, quantity, billing period and term dates.

  • state: active, canceled, expired, failed, future, paused
  • unit_amount, quantity, add_ons_total, subtotal
  • current_period_ends_at, current_term_ends_at, auto_renew
Core

Invoices, payments & dunning

/invoices · transactions · dunning campaigns

What each customer was billed, what they paid, what is past due and how far dunning has gone.

  • state: pending, processing, past_due, paid, failed, voided
  • total, balance, due_at
  • dunning_events_sent, final_dunning_event
Core

Webhooks

JSON or XML notifications, per endpoint

Recurly 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
Write-back

Purchases

/purchases · /purchases/preview · /purchases/pending

One 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
Enrichment

Usage

/subscriptions/{id}/add_ons/{add_on_id}/usage

Usage 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
  • amount and usage_timestamp per record
  • Rolled up per period, not copied line by line
Starting point

HubSpot's Recurly app

Built by HubSpot · data sync

Syncs 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
03 — Framework

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
Webhookssubscription, invoice, payment, dunning
Accounts & subscriptionsstate, plan, add-ons, term dates
Invoices & transactionsbalance, due date, dunning
Plans, add-ons & usagecatalog, intervals, usage records
CC integration layer
Webhook endpointsignature check, read-back via API
De-dup & orderingnotification ID · updated_at
Revenue engineMRR, ARR, renewals, currency rules
HubSpot writerupserts, associations, events
Purchase bridgedeal → Recurly purchase
HubSpot
Companies & contactsbilling account, revenue rollups
Subscriptions (custom object)plan, state, MRR, renewal
Invoices (custom object)balance, due date, dunning
Deals, products & line itemsnew business, renewals, expansion
Tasks, tickets & workflowsdunning, churn risk, renewals
Recurly → HubSpot (primary flow)HubSpot → Recurly (accounts and purchases from closed deals)
Principle

Recurly owns billing

Prices, invoices, payments and dunning run in Recurly. HubSpot stores them as reported and never recalculates a bill.

Principle

HubSpot owns the relationship

Companies, contacts, owners and the sales pipeline live in HubSpot. Recurly accounts link to them, not the other way round.

Principle

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.

04 — Process

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.

1

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.

Gate to next phaseSandbox keys issued and current app scope documented
2

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.

Gate to next phaseSigned revenue definitions and field ownership matrix
3

HubSpot data model

Create the Subscription and Invoice custom objects, company rollups, product properties, renewal pipeline and dunning ticket pipeline in a HubSpot sandbox.

Gate to next phaseSchema approved and created in sandbox
4

Inbound build

Build the webhook endpoint, signature check, read-back, ordering rules, revenue engine and HubSpot writer against the Recurly sandbox site.

Gate to next phaseAll subscribed notifications flowing end to end in sandbox
5

Write-back build

Build deal-to-purchase with a preview step, account creation from HubSpot, and validation against the synced plan catalog.

Gate to next phaseTest deal creates a Recurly subscription in the sandbox site
6

Backfill

Load accounts, live subscriptions, open invoices and an agreed history window through the list endpoints, then compute rollups once.

Gate to next phaseHubSpot MRR totals reconcile to Recurly reports within an agreed tolerance
7

Parallel run & launch

Switch to the production site with workflows paused, run two weeks in parallel, then switch on dunning and renewal automations.

Gate to next phaseFive consecutive days with no unresolved sync errors
05 — Data mapping

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 fieldHubSpot propertyObjectDirectionNotes
Accounts → companies & contacts
account.code + siterc_account_code, rc_siteCompanyRC → HSUnique per site; both stored.
account.emailemailContact↔ BothMatch key for the billing contact.
account.first_name, last_namefirstname, lastnameContact↔ BothFill blanks only; HubSpot edits stay in HubSpot.
account.companynameCompany↔ BothCompany created in HubSpot, then linked.
account.addressaddress, city, state, zip, countryCompanyRC → HSCountry codes normalized to HubSpot values.
account.parent_account_idParent company associationCompanyRC → HSRecurly account hierarchy as parent and child companies.
account.has_past_due_invoicerc_past_dueCompanyRC → HSFlag for lists and views.
Subscriptions → Subscription object & rollups
subscription.idrc_subscription_idSubscription (custom object)RC → HSUnique key.
staterc_stateSubscription (custom object)RC → HSactive, canceled, expired, failed, future, paused.
plan.code, plan.namerc_plan_code, rc_planSubscription (custom object)RC → HSPlan as a HubSpot product reference.
unit_amount, quantity, add_onsLine itemsSubscription (custom object)RC → HSPlan and add-ons with quantity.
subtotal ÷ plan intervalrc_mrrSubscription (custom object)RC → HSMonthly value per the signed definition; computed in the integration layer.
current_term_ends_at, auto_renewrc_renewal_date, rc_auto_renewSubscription (custom object)RC → HSFeeds the renewal pipeline.
trial_ends_atrc_trial_endSubscription (custom object)RC → HSTrial conversion workflows.
canceled_at, expires_at, expiration_reasonrc_canceled_at, rc_expiration_reasonSubscription (custom object)RC → HSChurn reporting.
sum(rc_mrr) of active subscriptionsrc_company_mrrCompanyRC → HSComputed in the integration layer.
rc_company_mrr × 12rc_company_arrCompanyRC → HSPer the signed revenue definitions.
Invoices, payments & dunning
invoice.numberrc_invoice_numberInvoice (custom object)RC → HSUnique per site.
staterc_invoice_stateInvoice (custom object)RC → HSpending, processing, past_due, paid, failed, voided.
total, balancerc_invoice_total, rc_balanceInvoice (custom object)RC → HS
due_atrc_due_dateInvoice (custom object)RC → HS
dunning_events_sent, final_dunning_eventrc_dunning_stageCompanyRC → HSLatest across open invoices.
payment failed notificationTask or TicketTicketRC → HSRouted to the account owner or customer success.
Catalog, purchases & write-back
plan and add-on codesProduct (hs_sku = plan or add-on code)ProductRC → HSRecurly owns the catalog.
HubSpot deal line itemsPOST /purchasesDealHS → RCPurchase created for the linked account after a preview.
HubSpot company and contactRecurly account (create)CompanyHS → RCOnly when a deal reaches the agreed stage.
subscription created notificationDeal stage: Closed wonDealRC → HSSubscription associated to the deal.
Usage
usage amount per add-onrc_usage_current_periodSubscription (custom object)RC → HSRolled up per billing period; usage-based add-ons only.
06 — Auth & API

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.

TopicRecurlyHubSpot
AuthenticationHTTP 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 & versioninghttps://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 & entitiesThe /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 securityHTTP 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 & retriesFailed 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 limitsProduction: 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 & licensingUsage-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.
07 — Issues & opportunities

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

MRR needs a definitionHigh

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.

MRR across currenciesHigh

Each subscription bills in its own currency. Finance picks a reporting currency and rate source before company rollups are built.

How deals model subscriptionsMedium

One deal per subscription, per renewal, or per expansion changes every report. Agree the pipeline design before backfill.

Small webhook payloadsMedium

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.

Several sites or business entitiesMedium

Account codes and invoice numbers are unique per site, not across sites. Every key is stored with its site, and catalogs are kept apart.

Two writers on the contactLow

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

Revenue on every companyHigh value

MRR, ARR, active plans and next renewal sit on the company record, ready for lists, views and reports.

Dunning handed to the right personHigh value

A failed payment or a past-due invoice opens a task or ticket for the owner, with the invoice attached, before the customer churns.

A renewal pipeline that runs itselfHigh value

Renewal deals are created ahead of the term end, so account managers see every renewal in one pipeline.

Purchases from HubSpot dealsMedium value

Sales builds the deal in HubSpot, previews the Recurly invoice, and the closed deal creates the subscription.

Usage as an expansion signalMedium value

Customers near a usage threshold enter an upsell list for their owner.

Churn reasons in reportingMedium value

Cancellation dates and expiration reasons sit beside marketing source and owner, so leaders see why customers leave.

Rollout order

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.

  1. Confirm what HubSpot's Recurly app already syncs, and agree which contact fields it keeps.
  2. Add Subscription and Invoice records, and company MRR and ARR rollups, from webhooks.
  3. Add dunning, failed payments and renewals as HubSpot tasks, tickets and pipeline.
  4. Add deal-to-purchase write-back last, once the catalog and accounts are matched.
08 — Property schema

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 nameLabelObjectTypeSource / logic
rc_account_codeRecurly Account CodeCompanySingle-line textaccount.code; unique with rc_site
rc_siteRecurly SiteCompanyDropdownSite the account belongs to
rc_company_mrrMRRCompanyNumber (currency)Sum of active subscription rc_mrr
rc_company_arrARRCompanyNumber (currency)MRR × 12, per signed definition
rc_active_subscriptionsActive SubscriptionsCompanyNumberCount of active subscriptions
rc_next_renewal_dateNext RenewalCompanyDateEarliest current_term_ends_at
rc_past_dueHas Past-Due InvoiceCompanySingle checkboxaccount.has_past_due_invoice
rc_balance_dueBalance DueCompanyNumber (currency)Sum of open invoice balance
rc_subscription_idRecurly Subscription IDSubscriptionSingle-line textsubscription.id; unique
rc_stateSubscription StateSubscriptionDropdownsubscription.state
rc_mrrSubscription MRRSubscriptionNumber (currency)subtotal normalized to one month
rc_invoice_numberRecurly Invoice NumberInvoiceSingle-line textinvoice.number; unique with rc_site
09 — Scope builder

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

0Fields
0Inbound
0Write-back
Recurly × HubSpot Integration Assessment · Designed by Campaign Creators, Elite HubSpot Solutions Partner

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.