What are Linked Terms, and why should a client use them?
Answer:
Linked Terms allow Piano’s system to integrate with a client’s external checkout and subscription management system. This enables clients to use their existing workflows for subscriptions and payments while leveraging Piano's features, such as audience segmentation, data analysis, and user journey orchestration. It’s particularly useful for clients who do not want to migrate their subscription management to Piano or require custom workflows that Piano’s native tools do not fully support.
How does the Linked Terms flow work?
Answer:
The flow typically involves these steps:
-
A user selects a subscription option from a Piano Offer Template (Linked Term) on the client’s website.
-
Piano triggers the linkedTermSelected event, passing information about the user and the selected term to the client’s system.
-
The user is redirected to the client’s external checkout to complete the payment.
-
The client’s backend sends a subscription creation event to Piano’s Sync API to ensure the subscription is synchronized in both systems.
-
From there, all subscription updates (e.g., renewals, cancellations) are communicated back to Piano through the Sync API.
What are the key benefits of using Linked Terms for clients?
Answer:
Linked Terms provide several benefits:
-
Flexibility: Clients retain control of their existing payment and subscription workflows.
-
Seamless Integration: Linked Terms act as a bridge between Piano and external systems, requiring minimal disruption to existing workflows.
What is the purpose of the linkedTermSelected callback?
Answer:
This callback allows a client to:
-
Start the purchase process in their native checkout
-
Retrieve the session id and thus associate user data tracked by Piano with subsequent purchase conversion
The linkedTermSelected callback is triggered when a user selects a Linked Term on the client’s website. It provides the following information:
-
Session ID: A unique identifier for tracking the user’s session in Piano. It’s a specific Linked Term session, not applicable anywhere else in Piano.
-
Linked Term Object: Includes data about the selected subscription option (e.g., external term ID and product details). The callback is crucial for initiating the external checkout process. The client’s system uses the data from the callback to redirect the user to the appropriate external checkout URL.
How can clients allow users to manage their Linked Term subscriptions in the "My Account" component?
Answer:
To enable users to manage their subscriptions via the "My Account" component:
-
Include a Subscription Management + Billing URL when creating a Linked Term in Piano. This URL should point to the client’s external system where users can view or update their subscription.
-
Piano’s "My Account" component will display a link or button pointing to this URL.
Can Linked Terms subscriptions be displayed alongside other Piano-managed subscriptions in "My Account"?
Answer:
Yes, Linked Terms subscriptions can appear in the "My Account" component alongside Piano-managed subscriptions. However:
-
Linked Terms subscriptions rely on the Subscription Management + Billing URL to direct users to the client’s external system for actions like cancellations or upgrades.
-
Piano’s "My Account" does not provide direct management capabilities (e.g., cancel, update) for Linked Terms but will list the subscription details and provide a link to the external system.
Is it possible to implement an External SSO for the Subscription Management + Billing URL such that a user is automatically logged in to the external system when they click on the Subscription Management + Billing URL?
Answer:
Yes, you can implement an External Single Sign-On (SSO) for the Subscription Management + Billing URL in a Linked Terms integration. This allows users to be automatically logged into your external system when they click on the Subscription Management + Billing URL.
However, the implementation must be completed on your side, as Piano does not have access to your external system. Our team can provide general guidelines and theoretical support to help you set it up.
Can we add a price to a Linked Term and use it in templates?
Answer:
While it’s not possible to set any billing plan/price for Linked Term in Subscription Management + Billing, it’s possible to specify term-level custom data that is available in:
-
Offer templates
-
linkedTermSelected callback and hence in client native checkout
Nevertheless, in Subscription Insights, the revenue report will be available because it uses the information about the price pushed to Piano after the conversion is made.
Can we apply coupons to a Linked Term?
Answer:
If a client wants to offer discounts, they will need to create additional Linked Terms with a new final price.
-
Linked Terms Sync API doesn’t provide any special fields to specify coupons/discounts/promotions.
-
It also doesn’t compare or validate prices. It’s possible to send any price within a subscription event. Two subscriptions with different prices (normal and discounted) might be converted to the same Linked Term, but it makes analytics and reporting in Piano less transparent.