Leveraging events in Affinity

Affinity utilizes events to broadcast crucial information, offering insights into user behavior and enabling the creation of synchronized custom content extensions.

Below is an overview of the various event types supported by Affinity and how they can be leveraged. Note that you must be on the Recharge Pro plan, or a Custom plan, to make advanced customizations to the Affinity customer portal.



  • Shopify Checkout Intergration
  • Recharge Checkout on Shopify

Available events

Event typePurpose
Click eventsClick events are events initiated by a user's actions, and primarily indicate intent. The click event is triggered at the initial step, capturing the user's initial intent. For example, the process of a user skipping their next order contains three events, the first being the click event:
Event 1: The user clicks the Skip button. The click event is triggered here.
Event 2: The user confirms their choice by clicking the Yes, skip this order button in the modal.
Event 3: Recharge skips the user's order.
Action eventsAction events signify the finalization of an action. Considering the example of a user skipping their next order contains three events, the final event, the actual skipping of the order, is considered the action event.
Navigation eventsNavigation events are emitted every time a user navigates to a new page in Affinity. Navigation events are used to understand user engagement and navigation patterns in the portal.
Slot lifecycle eventsSlot lifecycle events are triggered when slot content is added or removed from the Document Object Model (DOM).

These events are instrumental in managing the lifecycle of custom code linked to slot content
DirectivesThese events are listened to, rather than emitted by Affinity. These allow custom extensions to trigger specific behaviors within Affinity.

Events emitted by Affinity

EventEvent typeEvent name
Order nowClickRecharge::click::orderNow
Order nowActionRecharge::action::orderNow
Location changedNavigationRecharge::location::change
MountedSlot lifecycleRecharge::slot::mounted
UnmountedSlot lifecycleRecharge::slot::unmounted

Events Affinity listens for

EventEvent typeEvent nameAction
Refresh pageDirectiveAffinity:refreshTrigger a soft refresh of the page.
Open order nowDirectiveRecharge::order::openOrderNowModalOpen the order now modal for the next scheduled order in the /overview page.
Open rescheduleDirectiveRecharge::order::openRescheduleModalOpen the reschedule modal for the next scheduled order in the /overview page.
Open skipDirectiveRecharge::order::openSkipModalOpen the skip modal for the next scheduled order in the /overview page
UnskipDirectiveRecharge::order::unskipCall unskip function within in the /overview page to unskip the next scheduled order.
Open discountDirectiveRecharge::order::openDiscountModalOpen the discount modal from the order summary in the /overview page.

Practical application of events

Synchronizing Advanced Content Extensions with Affinity

Slot-powered content extensions function as independent modules within the Affinity ecosystem, which requires two-way communication established through events. This ensures that changes in your extension and Affinity stay synchronized and reflect updates in real-time on both sides.

Lifecycle management

Slot content in Affinity is dynamically loaded, meaning it is not present in the Document Object Model (DOM) during the initial page render but is added shortly afterward.

When developing advanced content extensions, a best practice is to use Slots for hosting initial placeholder elements. You can then wait for these elements to be present in the DOM before initializing your custom code.

Example: Initializing Custom Code in a Slot

Slot preparation
<script type="text/html" data-recharge-slot="overview.header">
  <div id="placeholder-for-my-app"></div>
Javascript initalization
document.addEventListener("Recharge::slot::mounted", (event) => {
  if (event.detail.name === "header" && event.detail.pathname === "/overview") {
    // Initialize my app

Respond to Affinity action events

Leverage action events in Affinity to adapt your custom content in response to user interactions. The example below highlights how you can monitor and respond to specific actions like rescheduling an order:

document.addEventListener("Recharge::action::reschedule", (event) => {
 //Refresh your slot custom content

Control Affinity from content extensions

Content within slots communicates with Affinity by emitting Directive events, which trigger designated actions. Use these actions to trigger specific events depending on the actions customers take.

Use the following example to emit a refresh event to trigger a page refresh, ensuring your customers access up-to-date data if they add a product to their next order from within a slot:

document.dispatchEvent(new CustomEvent("Affinity:refresh"));

Create personalized flows

Use Affinity to craft user experiences that meet your unique business needs. You can intercept the default behavior when a customer initiates an action, such as skipping, rescheduling, or canceling an order, and instead initiate a custom flow.

The following example highlights how to add your custom flow when a customer initiates the reschedule action:

document.addEventListener("Recharge::click::reschedule", (event) => {
 // Display custom reschedule UI

See Personalize user journeys with custom flow extensions to learn how to use a custom flow to change the cancelation flow for customers depending on the products customers subscribe to.


Use events to transmit data to your preferred analytics tools and gain insight int your users' behaviors:

  • Use Click and Action events to observe the completion rates when customers perform actions such as skipping or rescheduling an order or ordering a product immediately. This is achieved by comparing the initial click, which shows intent, against the completion of the action.
  • Use Navigation events to analyze user engagement and map out customer journeys within your portal. This helps in identifying popular paths and potential areas for improvement.
  • Use Slot lifecycle events to evaluate the performance of your advanced extensions. Gather data on impressions to understand the reach and effectiveness of your extensions.

Need Help? Contact Us