The subscription.updated event plays a pivotal role in the subscription lifecycle within our system. Triggered whenever there is a modification to any aspect of a subscriber's account—from renewal price, renewal quantity, renewal product, renewal type, expiration date, and immediate mid-term changes like immediately reducing the quantity and increasing the quantity—this event helps you stay informed about significant changes. Changes initiated through all channels, including Global Commerce, the High Availability Subscription API, integration jobs such as SSN/UM, and the Global Commerce-hosted storefront self-service page, will trigger this event
The previousAttributes object in this event provides invaluable insight into the specifics of these changes, highlighting the altered attributes and their state before the update. This level of detail is essential for maintaining accurate records, ensuring the continuity of services, and delivering exceptional customer service.
Previous attributes
When a subscription undergoes any modifications, such as changes in billing details, subscription period adjustments, or service type transitions, a subscription.updated event is generated. This event is crucial for tracking changes accurately to ensure the continuity of a seamless service experience for your customers.
A key component of this event is the previousAttributes object. This object encapsulates the details of what exactly changed during the update. It lists the attributes that were modified and provides the previous values of these attributes before the update took place.
For example, when a subscription's renewal type changes, the previousAttributes could look like this:
For a change from manual to auto-renewal:
"previousAttributes": {"autoRenewal":true}
For a change from auto-renewal to manual:
"previousAttributes": {"autoRenewal":false}
Handling a change to the renewal price
When the renewal price of a subscription changes, a subscription.updated event is fired. This event notifies stakeholders of any adjustments to the subscription cost for the upcoming renewal period. Understanding this event is crucial for maintaining transparency with subscribers and ensuring smooth subscription management practices.
Understanding the event structure
Upon a renewal price change, you will receive a subscription.updated event with the following structure:
type: Identifies the event type as subscription.updated.
data:
object: Contains details about the subscription, including ID, state, renewal quantity, and more.
renewalPrice: Details the new renewal price, including unitPrice and currency.
previousAttributes: Captures the state of the subscription before the update.
renewalPrice: Indicates the previous renewal price to allow for a clear comparison.
The previousAttributes section is especially important as it provides the old values before the update, enabling clear visibility into what has changed. Here's an example snippet indicating a price change:
Transparency: Subscribers are informed about the price change before their renewal date, maintaining trust.
Compliance: Ensures adherence to policies or regulations requiring pricing change notification.
Analytics: Helps in analyzing the impact of price adjustments on retention and revenue.
Any change in the renewal price is a critical event that requires attention to manage subscriber expectations effectively and comply with service agreements.
Handling a change to the subscription renewal date
In the lifecycle of managing subscriptions, adjusting the renewal date is a common and necessary action to accommodate various scenarios, such as extending a trial period, aligning billing cycles, or responding to customer requests. The subscription.updated event is crucial as it notifies when there's a modification to the subscription's renewal date. This section offers a comprehensive guide on handling such updates efficiently, ensuring smooth subscription management while maintaining transparency with subscribers.
Handling a change to the subscription renewal product
The subscription.updated event is triggered whenever a product is modified associated with a subscriber's renewal period. This can include changes such as updating to a new product version, switching to a different product that better suits the subscriber's needs, or modifying the product's components, including add-ons. This event ensures that subscribers and service providers are informed about the upcoming changes to the subscribed product before the current subscription term renews.
Key information provided in the event's payload includes:
id: The subscription identifier.
renewalProduct: Details of the new product for renewal, including product id, displayName, and sku.
previousAttributes: Shows the renewalProduct details before the update, allowing an easy comparison between the old and new renewal products.
Understanding and handling this event is crucial for maintaining transparency with subscribers and ensuring a seamless transition to the new product.
Handling a change to the subscription renewal type
When the renewal type of a subscription changes, a subscription.updated event is triggered. This event signifies a modification in how the subscription will be renewed – switching between manual and automatic renewals. It's a critical update that reflects either a change in customer preference or an adjustment in business strategy regarding the subscription.
Key details in the event payload:
id: Subscription identifier.
autoRenewal: Boolean value indicating if the renewal is set to automatic (true) or manual (false).
previousAttributes: Contains the subscription attributes before the update, allowing for a comparison. For the renewal type change, it will typically show "autoRenewal": true or "autoRenewal": false depending on the initial setup.
