Collapse Menu
Docs Home
Extensibility Options
Contact Support

Subscription Integration

Overview

This page describes the integration flow when using subscriptions.  Subscriptions follow the standard order flow during the initial purchase.  After the initial purchase the subscription becomes active and follows the integration flows below throughout the lifecycle of the subscription instance.  The update, charge managed subscriptions, and cancel subscription functions are also available through the Dashboard.

Overview

This page describes the integration flow when using subscriptions.  Subscriptions follow the standard order flow during the initial purchase. After the initial purchase the subscription becomes active and follows the integration flows below throughout the lifecycle of the subscription instance.  The update, charge managed subscriptions, and cancel subscription functions are also available in Dashboard.

A subscription is a product pricing scheme with regular on-going or recurring charges instead of a one-time purchase fee. A subscription contains a subscription definition. Each subscription definition includes: how often payments are due, the payment amount, and how long the payments last. Subscription pricing schemes can also include free trial periods and discounted pricing for a specified period. When defining the subscription you will need to indicate how often future billing for the subscription will occur.  The subscription can be set to automatically rebill at a specific interval by setting a recurring period. If you prefer to rebill using another method in partnership with the FastSpring API  or manually through Dashboard, you should set the rebill period to adhoc. This allows you to set the billing periods through other methods and then pass the rebill information to FastSpring. There are two types of subscriptions depending on how the future billing occurs. 

  • Regular - regular subscriptions are rebilled at the intervals specified in the product's subscription definition. These rebill charges can occur automatically on the next scheduled billing date using the payment details entered during the original purchase, or you can allow customers to opt out of saving the payment details, creating a manual renewal subscription instead. For manual renewal subscriptions, customers must log on to FastSpring's customer-facing account management site and make a payment on or prior to the next billing date.
  • Managed - with managed subscriptions, the rebills are considered "adhoc" and are triggered through the API or via Dashboard instead of using an automated process.

The two types of subscriptions follow the same basic flow except for the ongoing charges. With a managed subscription, you must initiate the ongoing charges through the Dashboard or the FastSpring API using POST /subscriptions/charge. On the Dashboard you can click CHARGE on the subscription detail page to initiate a new rebill charge.

All of the information about a subscription can be passed between you and FastSpring using the FastSpring API or entered or updated manually through the Dashboard. You will use the Subscriptions tab of the Products menu (in Dashboard) or the /products endpoint (via the FastSpring API) to create or update a subscription product. A subscription instance will automatically be created when a session or order contains a subscription product. Once the subscription instance is created, you will use the Activity menu (in Dashboard) or the /subscriptions endpoint (via the FastSpring API) to manage the subscription.   

The flow for subscription orders is the same as the flow for one-time orders up to the point where the customer has paid the initial payment and the subscription becomes active. At this point, a separate subscription instance is created with a unique identifier (the subscription ID) for each subscription item in the order. All of a customer's subscriptions are associated with the customer's account. Except in the case of manual renewal subscriptions, your customers will be required to provide payment information when making their initial subscription payment. This same information will be used for their future subscription payments. Depending on how you configure your stores, the payment information is kept as long as the subscription is active or it can be maintained even without an active subscription if agreed to by the customer.

 Adding or Removing Subscription Items to an Order

Once a subscription becomes active and the subscription instances have been created for the items within an order, the items be managed separately. For instance:

  • If you want to remove a line item, you must cancel the subscription id associated to the line item. The id can is obtained through the subscription.activated webhook event or by using one of the GET /subscriptions options.
  • If you want to add a line item, you must create a new order containing the new subscription product. Since the customer already exists with a payment method on record, you can use the /orders endpoint to add a new order. You will need the customer account id to create the order. This can be obtained through the various webhook events (including account.created ) or from the /accounts API endpoint.
  • Future orders created within your Store using the same email address will be added to the same customer account as previous subscriptions. 

New Subscriptions 

When a new subscription is created the subscription.activated webhook event will fire with the information about the subscription. If you are managing the subscription or would like to store the automated subscription information on your system, you can obtain the subscription summary by subscribing to that webhook event, or by using one of the GET methods described in this document. Once you have received the subscription information you can use GET /subscriptions/{id1}/entries to retrieve the charging period details.   

New Subscription Flow

User-added image

 Active Subscriptions

Subscriptions that have a subscription instance and have not reached their end date or been cancelled are considered active. Once the charging event trigger has occurred on an active subscription, both regular (automatic) and managed subscriptions will process through the same flow. The charging event trigger for a managed subscription is the POST /subscriptions/charge request sent to FastSpring or by clicking CHARGE in the subscription's details in the Dashboard. The charging event trigger for an regular automatIc subscription is the payment due date. Unlike  a managed subscription, an regular subscription is self-managing. The price and recurring periods are based on the product at the time of purchase. When a subscription product is changed, most changes only affect future subscription instances. Existing subscription instances are generally not automatically updated, although you do have the option to automatically update certain existing subscription instances when changing notification and cancellation settings

At each charging event the subscription price is automatically charged to the customer's payment method associated with the subscription instance. Failure to charge the payment method (e.g. a declined transaction) may result in a series of customer notifications and eventually lead to termination of the subscription. All customer and vendor notifications are automatically generated based on events and system configuration.

Events that can trigger email notification to customers:

  • Subscription activated
  • Trial period ending reminder
  • Payment due reminder
  • Subscription charge completed (similar to the default order receipt)
  • Subscription charge failed
  • Payment past due (series of notifications at configurable intervals)
  • Subscription updated
  • Subscription canceled
  • Subscription deactivated
  • Return / refund processed

Webhook vendor notifications that can fire for a subscription:

  • subscription.activated
  • subscription.trial.reminder
  • subscription.payment.reminder
  • subscription.charge.completed
  • subscription.updated
  • subscription.canceled
  • subscription.deactivated
  • subscription.charge.failed
  • subscription.payment.overdue
  • return.created

Active Subscription Charge Flow

The subscription charge flow is initiated daily by FastSpring or immediately when a managed subscription charge transaction is received. The process finds all subscriptions with a rebill or charge date equal to the current date or before and bills the customer's payment method associated with the subscription instance. If the payment method does not exist or is invalid, the subscription dunning (past due) process will be initiated.  Successfully completing the charge will reset the dunning process. 

If the end date of the subscription has been reached, the subscription will be deactivated and the subscription.deactivated webhook event will fire. This webhook event is the only notification that will be provided when a subscription has reached its end date. The subscription.deactivated webhook event will also fire when a subscription is cancelled immediately or is cancelled due to non-payment. 

Subscription Charge Flow

User-added image

Charge Managed Subscriptions

Subscription charges can be managed automatically by FastSpring (see above) or you can manage the subscription. When managing subscriptions directly, you must initiate the charge transactions through the Dashboard or through the FastSpring API. Subscription details can be obtained through the subscription.activated webhook event or by using one of the GET methods described in this document. Initiating the POST /subscriptions/charge request will trigger the next payment to be processed. Once the payment charging request is received, the subscription will immediately follow the Active Subscriptions flow described above.

Charge Managed Subscriptions Flow
User-added image

Subscription Payment Notifications

There are two types of subscription payment notifications that can be used to notify you and your customers when a payment is due or overdue:

  • Payment reminder - this notification is optional and can be configured to be sent a specific number of days prior to the payment due date. You can optionally schedule multiple payment reminders to be sent prior to each billing.
  • Payment overdue - this notification series can be used to  inform your customers when their payment is past due. You can set the intervals and actions for these reminders, and and if you elect to use these reminders, the date of automatic cancellation due to non-payment will be based on the date of the final overdue reminder. 

A daily process determines which event (reminder, overdue, or deactivation) is scheduled to occur and then generates the webhook to execute the event. 

Subscription Customer Payment Notification FLow

User-added image

Update Subscriptions

This flow is used when the next charge date, end date, product, or quantity needs to be changed. You also have the option to override generate a an automatic, prorated charge or refund through the Dashboard or the FastSpring API when a subscription is changed in the middle of a billing period. If you attempt to update the next charge date and set prorate to true, the request will result in an error condition. The flow assumes that you already have the subscription ID(s) for the subscription(s) that you are updating. If needed, you can use the GET functions to obtain the subscription IDs. 

Changes made to a subscription that is in the middle of a billing period could generate an additional charge or refund to the customer if the change takes effect in the current charging period. This is accomplished by passing "prorate":true when updating a subscription via the API, or by clicking the PRORATE command in Dashboard after making subscription edits. Charging periods that are prorated will typically result in an additional charge or refund to your customer. You will be notified of the charge/refund through webhooks and the customer will be sent subscription updated and subscription charge completed (or return completed) email messages.

 

Update Subscriptions Flow

The following apply to subscription updates using the POST /subscriptions endpoint:

  • The FastSpring API can only be used to apply changes to the main subscription product. Dashboard should be used to update subscription addons. 
  • By default, changes to the subscription instance will take effect on the next charge date unless "prorate" is set to true in the POST /subscriptions request.
  • The POST /subscriptions request must contain exactly one main subscription product.
  • Only those values that are being changed need to be specified in the payload. 
  • Changes to the next charge date may not be an historical date. It can only be changed to a future date.
  • Payment details are part of the customer account and cannot be updated through /subscriptions. Customers should use FastSpring's customer-facing account management site to update their payment information. 
  • When passing "prorate":true, updates that result in a payment due or refund for the current period will result in a charge or refund posted to the customer's payment method associated with the subscription instance. 
    • A charge will fire the subscription.charge.completed webhook event.
    • A refund will fire the return.completed webhook event.
    • The subscription.updated event will also fire regardless of whether or not you prorate. 

User-added image

Cancel Subscriptions

Using the FastSpring API, you have the option of cancelling a subscription at the end of the current period or immediately. Cancelling at the end of the current period is the default, however if you add ?billingPeriod=0 to the DELETE method, the subscription will be canceled immediately. Two webhook events can file when a subscription is canceled:

  • subscription.deactivated - will fire when a subscription is canceled immediately through the API or Dashboard.
  • subscription.canceled - will fire when the subscription cancel request is completed through the API without ?billingPeriod=0, or through Dashboard with the option to Deactivate at next period selected. (In this case, subscription.deactivated would also fire later, on the deactivation date.)
Cancel Subscriptions Flow
User-added image
 

Get Subscriptions

When working with subscriptions, you must have the unique subscription ID in order to perform any action against the subscription. You can obtain the subscription ID by subscribing to webhooks or using GET /subscriptions. Using GET /subscriptions will return a list of all active subscription identifiers. You can limit the number of subscription instances returned per page using "&limit=", and you can control pagination of the API response using "&page=". Adding one or more subscription identifiers to GET /subscriptions will return the details of the specific subscriptions. Issuing the GET/subscriptions/{id1}/entries request will generate a response that includes all of the rebill transactions for the subscription.  

Get Subscriptions Flow

Since each item in an order will generate a subscription instance with a unique ID, to obtain the subscription information for the entire order you must specify all subscription identifiers in the GET request.

User-added image

Try FastSpring

Get a free account and see why FastSpring is the ecommerce partner of choice for software providers around the world. Try our full-service ecommerce solution today to unlock revenue growth for your online company.