We’ve migrated our documentation to a new site, which means some URLs have changed.
Subscriptions
Subscriptions
Breadcrumbs

Importing Dynamic Subscriptions

Introduction

This guide provides detailed instructions for importing dynamic subscriptions into Piano. It includes import file specifications, an explanation of key parameters, and examples to ensure a smooth transition from external systems to Subscription Management + Billing. This process supports various scenarios involving billing plans, payment tokens, and dynamic term configurations.

Preparing the Import File

File Specifications

  • Filename Format: Use the format AID_dynamic_subs_PAYMENTPROVIDER.csv. For example:

    • uTIyZr2su_dynamic_subs_braintree.csv

    • uTIyZr2su_dynamic_subs_mock.csv

  • Separate Files for Each Payment Provider: Ensure that each payment provider, and subscriptions without tokens, have their own CSV file.

  • Format and Encoding:

    • File Format: Must be .csv (comma-separated values).

    • Encoding: UTF-8 is required.

  • Column and Row Rules:

    • All columns (user_id, term_id, renewal_period_id, vx_purchases_start_date, imported_period_start_date, imported_period_end_date, imported_period_billing_plan, imported_period_grace_period, customer_id, payment_method_token, card_id, provider_input_params, expiration) from this template must be present in the file, even if some remain unpopulated.

    • Columns that are marked in the template as mandatory (user_id, term_id, imported_period_start_date, imported_period_end_date - highlighted in red) must be filled with supported values.

    • No additional columns or rows should be included.

    • All dates specified in the file must adhere to the application's time zone.

Subscription Requirements

  • Eligible Subscriptions: Only subscriptions to dynamic terms can be imported via this file. Other subscription or access types like registration, single payment, recurring payment terms, external terms, scheduled terms, granted access, and site license contracts must be handled separately.

Key Parameters

Essential Parameters for Import of Dynamic Subscriptions

  1. user_id (Mandatory)

    • Definition: Id of an already imported or existing user in Piano application.

    • Constraints: You'll need to ensure that each user_id corresponds to an already existing user in the Piano application

  2. term_id (Mandatory)

    • Definition: The dynamic term ID.

    • Constraints: This ID has to match an existing Term ID of a dynamic term in the application.

  3. imported_period_start_date (Mandatory)

    • Definition: The start date of the period in the external system. It marks the subscription's creation start date in Subscription Management + Billing.

    • Constraints: Must be ≤ import date and ≤ vx_purchases_start_date and < imported_period_end_date.

    • Example: If a user was last charged on April 17, 2024 (outside of Piano), this is the date to input.*

  4. imported_period_end_date (Mandatory)

    • Definition: Indicates when the imported period concludes and the subscription renewal to the first access period in the dynamic term or the access period specified in the "imported_period_grace_period" column occurs.

    • Constraints: Must be ≥ import date, ≥ vx_purchases_start_date, and > imported_period_start_date.

    • Example: If a subscription end date is set to December 17, 2024, the renewal in Piano will be on this day.

  5. imported_period_billing_plan (Optional)

    • Definition: The billing plan from the external system used during the imported period.*

    • Options:

      • Relative Billing Plan: Describes periodic charges (e.g., $0.99 every 10 days).

        Examples:
        [0.99 USD | 10 day] - $0.99/every 10 day(s)
        [1.99 USD | 2 week] - $1.99/every 2 week(s)
        [5.99 USD | 3 month] - $5.99/every 3 month(s)
        [18.99 USD | 1 year] - $18.99/every 1 year(s)

        Parameters:
        a) price
        b) currency - the currency of the imported period must match the one configured for the dynamic term
        c) number of periods - available values: from 1 to infinite
        d) period - available values: day, week, month, year

      • Free Billing Plan

        Example:
        [0 USD]

        a) price - always "0"
        b) currency - the currency of the imported period must match the one configured for the dynamic term

        The field can also be left blank. In this case, we consider it to be a free billing plan.

  6. vx_purchases_start_date (Optional)

    • Definition: The date when Subscription Management + Billing starts processing payments.**

    • Constraints: Should be ≥ import date, ≥ imported_period_start_date, and ≤ imported_period_end_date.

    • Usage: Typically set the same for all subscriptions to indicate when you stop billing in the old system. The field can also be left blank. In this case, we consider it equivalent to the import date, meaning that the next billing date of the imported subscription can coincide with the import date.

  7. renewal_period_id (Optional)

    • Definition: Specifies the access period of the dynamic term for a subscription's first renewal in Subscription Management + Billing.

    • Usage: Use to avoid default trial periods or ensure renewal to a specific access period in the dynamic term. The access period must not be removed, marked for removal, or end before the planned renewal date. If not specified, the subscription will be imported without a scheduled access period and renewed to the first period in the dynamic term's billing configuration on the next billing date.

* Since subscriptions cannot be imported in the middle of a dynamic term period, all imported subscriptions will be assigned a custom imported access period. After this access period ends, they will transition either to the first billing access period configured in the dynamic term or, if a renewal_period_id is specified, to a specific billing access period within the dynamic term (e.g., to bypass the trial for users who have already completed it).

**By adjusting the vx_purchases_start_date, the publisher can control how many renewal cycles they will handle themselves (outside of Piano) and how many will be managed by Piano as defined in the imported_period_billing_plan. For example, if the publisher sets imported_period_start_date to December 17th, vx_purchases_start_date to December 23rd, and imported_period_end_date to January 17th, Piano will not charge the end user on December 17th but will maintain their access, assuming the publisher has already charged the user through their previous system.

Optional Payment Token Fields

  • Fields for Importing Payment Tokens (mandatory fields vary by provider):

    • customer_id

    • payment_method_token

    • card_id

    • provider_input_params

    • expiration

Handling Payment Tokens

  • With Tokens Ready: Include payment token data within the import file.

  • Without Tokens Ready: Payment tokens can be imported later via a separate file, or users must enter their payment details manually in order for the next subscription renewal to be processed successfully. Ensure tokens are prepared before the next billing date to prevent subscription expiration.

Grace Period

  • imported_period_grace_period (Optional):

    • Definition: Grace period length in days, setting for handling payment failures during the imported_period_billing_plan before the vx_purchases_start_date. On the subscription renewal on the imported_period_end_date the grace period configured on the term will be applied.

    • Constraints: Must be ≤ 60 days and ≤ the length of the billing period of the imported period.

    • Usage: The field can be left blank, which defaults to 0, meaning no grace period during the first (imported) access period. If payment fails during any renewal of the imported period, the subscription won't enter a grace period and will expire.

This is the only place to set the grace period length for the imported period, and it cannot be changed after the dynamic subscription creation.

For imports to applications with Passive Churn Prevention enabled, this field is ignored. The application's default churn prevention logic will apply to the imported period, and all grace period settings will be based on that logic.

Key Considerations

Defining Access Periods in Dynamic Subscription Imports

The import process for dynamic subscriptions is designed to be both flexible and precise, allowing for the specification of various access periods through a series of parameters. The current import model relies on specifying a dedicated period in the file using the billing plan and three pivotal dates: imported_period_start_date, imported_period_end_date, and vx_purchases_start_date.

Dynamic subscription imports result in users beginning in an "imported" custom access period, followed by a switch to the first or specified access period of the dynamic term.

Please note that import dates should be adjusted based on the database time zones used by the specific Piano dashboards. For example, the US dashboard database runs on EST. If your application is set to UTC+1 (CET), which is 6 hours ahead of server time, you'll need to apply a time offset to align the data correctly. For instance, if your local time is 11/10/2023 10:00 CET, you should enter it as 11/10/2023 16:00 in the import file so that it matches the correct server time.

Transition Between Periods

An essential aspect of managing subscription imports is understanding when and how users transition from one period to another. The imported_period_end_date plays a vital role here. Subscriptions initially live in the custom-imported access period, transitioning to the next specified period in the dynamic term once this end date is reached.

The renewal_period_id defines which access period follows the imported period.

Import Process Overview

  1. CSV Preparation: Arrange your data within a CSV format, following the specifications above. Include all mandatory columns, and ensure dates comply with the application’s time zone.

  2. Set Correct Parameters:

    • For imported_period_start_date: Reflect the start of the subscription in the external system.

    • For imported_period_end_date: Determines the transition date to the next dynamic term billing period.

    • For imported_period_billing_plan: Match the billing details from the old system or set it to free, depending on the need for this information to be present in Piano.

  3. Configure vx_purchases_start_date:

    • Align users by setting a universal date to transition billing responsibilities from the old system to Piano.

  4. Use of renewal_period_id:

    • Ensure correct initial access period post-import by specifying this ID, especially if skipping the default first period (e.g. trial).

  5. Setting Up Payment Providers:

    • Confirm payment provider configurations are active in the Piano dashboard under Edit Business → Payment provider before proceeding with the import.

  6. Analysis and Execution:

    • Your Project Manager or assigned L2 Support agent will verify the file format and content accuracy, then proceed with the import following the processes outlined in the Piano documentation.

Use cases

Importing subscribers mid access period

A publisher uses a Dynamic Term with two Access Periods (APs). The first AP offers a discounted price for X billing periods. Some users have already been billed Y times before being imported into Piano. After import, they should continue to receive the discounted pricing for the remaining X-Y billing periods. Once the X discounted billing periods are completed, billing should automatically transition to the second AP at the standard rate.

How to configure the import file:

renewal_period_id - should be the second AP
vx_purchases_start_date - in case you turn off your old subscription system on the import date, leave it blank
imported_period_start_date - the date when the subscription began
imported_period_end_date - the date when the discounted AP should end
imported_period_billing_plan - the discounted period billing plan, for example [10.99 USD | 4 week]
imported_period_grace_period - optional but recommended

Last updated: