ClearSync creates records on two HubSpot app objects:
- ClearSync Stripe Subscriptions represent the current state of each Stripe subscription.
- ClearSync Stripe Events represent individual MRR change events such as new sales, upgrades, downgrades, and churn.
These records can be edited after ClearSync creates them. This is useful when your internal billing logic requires context that Stripe doesn’t express cleanly, for example, if a product upgrade cancels one Stripe subscription and creates another.
This article explains the available implementation options.
Common use cases for modifying ClearSync records in HubSpot
Example use cases where it might make sense to modify ClearSync data include:
- Reclassifying a replacement subscription from New Sale to Upgrade.
- Changing the MRR change amount on an event.
- Removing or neutralizing a churn event that represents a technical migration rather than true customer churn.
- Setting custom fields on the ClearSync objects, for example, to record the Stripe subscription ID that preceded or succeeded another subscription.
- Creating custom association logic with Contacts, Companies, Deals, or Payment records.
- Applying company-specific MRR/ARR rules that ClearSync cannot infer from Stripe alone.
- Bringing in external data sources for subscriptions and payments, for example, automating record creation to represent app store recurring revenue processed outside of Stripe
Available mechanisms for modifying ClearSync data in HubSpot
Option #1: Use a HubSpot Workflow with a Custom Code Action
Requires HubSpot Data Hub Professional or Enterprise
A HubSpot custom code action within a Workflow can run JavaScript or Python inside a workflow and call HubSpot’s APIs.
This is generally the most convenient option when:
- The adjustment needed can be detected using data already available in HubSpot.
- The logic should run shortly after ClearSync creates an event.
- A non-engineering HubSpot administrator values visibility into the automation.
- You want to minimize using middleware and centralize logic in HubSpot as much as possible.
HubSpot currently makes custom code workflow actions available with Data Hub Professional or Enterprise. The action can be triggered by the creation of a ClearSync record and can accept any HubSpot record properties as inputs, call HubSpot or external APIs, and return outputs to later workflow actions.
A typical workflow might:
- Enroll when a ClearSync Stripe Event is created
- Delay briefly (e.g., 3 minutes) to allow ClearSync associations and related records to finish syncing.
- Determine whether the event represents a special case that needs handling.
- Run custom code that either updates data on the record or on associated records, or creates or updates associations to other records.
- Save any audit properties indicating that the adjustment occurred.
Option #2: External service or middleware
No HubSpot version requirements
An external service can use HubSpot’s CRM APIs to find and update ClearSync records.
Possible implementations include:
- Code running in the customer’s product backend
- A serverless function
- An integration platform
- A data warehouse reverse-ETL process
- An internal billing-service webhook handler
This approach is usually preferable when your product already knows exactly what’s happened and what needs to be done. That context can be sent directly to HubSpot or processed by middleware. The integration could then locate the corresponding ClearSync records and update them. This is usually the best option when:
- You do not have access to HubSpot Data Hub Professional+
- The relevant context exists only in your product database
- The logic needs source control, automated testing, or deployment controls
- A large number of records need to be updated in batches
HubSpot’s APIs support retrieving, searching, creating, updating, and batch-updating records. A record update is a partial update: only the properties included in the request are changed.
Option #3: HubSpot Workflow webhook to an external service
Requires HubSpot Data Hub Professional or Enterprise
A HubSpot Workflow can invoke an external endpoint, with the external service performing the actual HubSpot API operations.
This hybrid architecture is useful when:
- HubSpot is the best place to define enrollment criteria
- The code needs to run on your own infrastructure
- The operation requires custom libraries, execution time, or observability
The workflow can send the ClearSync record ID, Stripe subscription ID, Contact ID, Company ID, and other relevant values to the external endpoint.
The endpoint then authenticates to HubSpot, performs the updates, and optionally writes a success or failure status back to the record.
Authentication and required scopes
The ClearSync App Objects have the following API names:
javascript"a10608503_cls_stripe_subscription"
javascript"a10608503_cls_stripe_transaction"
An API request must use an access token authorized to interact with the applicable ClearSync app object. ClearSync’s app configuration defines separate app-specific scopes for its two objects.
ClearSync Stripe Subscription scopes
- crm.app.schemas.a10608503_cls_stripe_subscription.read
- crm.app.objects.a10608503_cls_stripe_subscription.view
- crm.app.objects.a10608503_cls_stripe_subscription.create
- crm.app.objects.a10608503_cls_stripe_subscription.edit
- crm.app.objects.a10608503_cls_stripe_subscription.delete
- crm.app.objects.a10608503_cls_stripe_subscription.merge
ClearSync Stripe Event scopes
The object shown to users as ClearSync Stripe Events uses stripe_transaction in its technical name:
- crm.app.schemas.a10608503_cls_stripe_transaction.read
- crm.app.objects.a10608503_cls_stripe_transaction.view
- crm.app.objects.a10608503_cls_stripe_transaction.create
- crm.app.objects.a10608503_cls_stripe_transaction.edit
- crm.app.objects.a10608503_cls_stripe_transaction.delete
- crm.app.objects.a10608503_cls_stripe_transaction.merge