Collapse Menu
Docs Home
Extensibility Options
Contact Support

Subscription Integration

Overview

This article explains the flow of subscriptions to help you integrate your systems with your FastSpring Store for subscription management.

This article describes how you can integrate your systems with FastSpring subscriptions.

After a customer places an order that includes a subscription product, FastSpring creates and activates a subscription record that is separate from the order record. Each subscription instance has a unique subscription ID. Subscription instances follow the integration flows described below.

 

Types of Subscriptions

There are two main types of subscriptions, which differ chiefly in how future billings occur. 

  • Standard: With standard subscriptions, FastSpring automatically rebills the customer at intervals specified in the subscription product's Pricing object. Typically, these rebill charges occur automatically on the next scheduled billing date using the payment details entered during the original purchase. Alternatively, 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 before the next billing date.
  • Managed: With managed subscriptions, the rebills are only triggered by you, through the FastSpring API or via the FastSpring App on demand, 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 FastSpring App or the FastSpring API. On the FastSpring App, you can click Charge on the subscription detail page to initiate a new rebill charge. To do this via the API, make a POST request to /subscriptions/charge.

 

Creating a Subscription Product

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 FastSpring App. Use the Subscriptions tab of the Products menu (in the FastSpring App) or the /products endpoint (via the FastSpring API) to create or update a subscription product.

Subscription Instance Creation

FastSpring automatically creates a subscription instance when a customer places an order that contains a subscription product. Use the Activity menu (in the FastSpring App) or the /subscriptions endpoint (via the FastSpring API) to manage the subscription.

All of a customer's subscriptions are associated with the customer's account. If the customer purchases a manual renewal subscription, FastSpring does not store the customer's payment details. Otherwise, we receive a payment token from our payment gateway that uniquely identifies the customer's payment account. We store the token in association with the customer's account and use it for the customer's subsequent subscription payments. Customers can view, add, and remove their stored payment methods via account management.

Adding or Removing Subscription Items to an Order

Each subscription instance is associated with one primary product. Except for subscription addons, each subscription has only a single product at any given time. For example, if a customer placed a single order for two subscription products, FastSpring would create two subscription instances for the customer.

 Tip

If you use Advanced Subscription Scheduling, you can configure a subscription product to create subscription instances that last a finite period and then renew into a different product. In that case, a customer's subscription instance would have two products--but only one active at any given time.

You can add or remove subscription addons via the subscription detail page in the FastSpring App, or via a POST request to the /subscriptions API endpoint. Before you can add subscription addons to a subscription instance, the addons must be configured for the subscription product.

If you want to make changes to a subscription instance using the API, you need to know the subscription ID. You can obtain this either from subscription-related webhook events such as subscription.activated or by calling GET /subscriptions with query parameters. Another option is to call GET /accounts; the API response includes all subscription IDs associated with the specified customer account. 

 

New Subscriptions 

When a new subscription is created, the optional subscription.activated webhook event fires with the information about the subscription. If you want to receive the details for new subscriptions, you can subscribe to that event. Alternatively, you can use one of the GET methods described in this document to retrieve subscription details. Using the subscription ID from either method, you can use GET /subscriptions/{id1}/entries to retrieve the details of rebill transactions. 

New Subscription Flow

 

Active Subscriptions

The default status for new subscriptions is active. Each subscription record has one or more sets of instructions that define the timing and other details for all rebills. When a subscription product is changed, most changes only affect future subscription instances. Existing subscription instances are generally not automatically updated. However, you do have the option to automatically update certain existing subscription instances when changing notification and cancellation settings.

Each time a subscription rebill occurs, FastSpring automatically charges the subscription price to the customer's payment method associated with the subscription instance. Failure to charge the payment method (e.g., due to a declined transaction) results in the subscription status changing to overdue. An email message is immediately sent to the customer, letting them know that the subscription rebill was not successful. You can optionally configure additional overdue reminder notices to be sent after the initial message. If the buyer does not resolve the issue with the declined rebill by updating payment details on the account management site, the subscription is eventually deactivated.

Events that can trigger an 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 overdue (series of notifications at configurable intervals)
  • Subscription updated
  • Subscription canceled
  • Subscription deactivated
  • Return/refund processed

Webhook events that can fire for a subscription (you can subscribe to each notification a la carte):

  • subscription.activated
  • subscription.trial.reminder
  • subscription.payment.reminder
  • subscription.charge.completed
  • subscription.updated
  • subscription.canceled
  • subscription.uncanceled
  • 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 request is received. The daily 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 (overdue) process is initiated. A successful charge on an overdue subscription will reset the dunning process. 

If the end date of the subscription has been reached, the subscription is deactivated and the subscription.deactivated webhook event fires. This webhook event is the only notification that occurs when a subscription has reached its end date. The subscription.deactivated webhook event also fires when you cancel a subscription with immediate effect, or when a subscription is canceled due to non-payment. 

Subscription Charge Flow

 

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 FastSpring App or the FastSpring API. You can obtain subscription details through the subscription.activated webhook event or by using one of the GET methods described in this document. Initiating the POST /subscriptions/charge request triggers the next payment to be processed.

Charge Managed Subscriptions Flow

 

Subscription Payment Notifications

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

  • Payment reminder: This notification is optional. You can configure it to be sent a specific number of days before the payment due date. You can optionally schedule multiple payment reminders to be sent before each billing. You can configure this via the Pricing field of the subscription product. Subscription instances created for the product inherit these settings.
  • Payment overdue: This optional notification series reminds your customers when their payment is past due. You can set the intervals for these reminders via the Pricing field of the subscription product. Subscription instances created for the product inherit these settings. 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

 

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 generate an automatic, prorated charge or refund through the FastSpring App or the FastSpring API after changing a subscription instance in the middle of a billing period. In the FastSpring App, after confirming the changes, the Prorate command appears on the subscription details page. When updating a subscription via POST /subscriptions, pass "prorate": true if you want to prorate the changes.

If you attempt to update the next charge date and set prorate to true, the request results in an error condition.

For the subscription change, the subscription.updated event fires (if you have subscribed to that event). FastSpring sends the subscription updated email message to the customer.

You can receive notifications of the prorated charge or refund through the subscription.charge.completed or return.created webhook events. FastSpring sends subscription updated and subscription charge completed email messages to the customer.

The following flow assumes that you already have the subscription ID(s) for the subscription instance(s) that you are updating. If needed, you can use the GET functions to obtain the subscription IDs. 

Update Subscriptions Flow

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

  • 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.
  • You only need to specify those values that you are changing in the payload. 
  • Changes to the next charge date may not be a historical date. You can only change it 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 automatically trigger a charge or refund posted to the customer's payment method associated with the subscription instance.
    • A successful charge fires the subscription.charge.completed webhook event.
    • A refund fires the return.completed webhook event.
    • The subscription.updated event also fires regardless of whether or not you prorate. 

 

Cancel Subscriptions

Using the FastSpring App or the FastSpring API to cancel a subscription, you have the option of deactivating the subscription at the end of the current period or immediately. Deactivating at the end of the current period is the default. However, when canceling via the FastSpring App, the app prompts you to choose whether to Deactivate at Next Period or Deactivate Now.  Similarly, when canceling via the FastSpring API, you can  add ?billingPeriod=0 to the DELETE method, to deactivate the subscription immediately. Two webhook events can fire when a subscription is canceled:

  • subscription.deactivated:  Fires when a subscription is canceled immediately through the API or the FastSpring App.
  • subscription.canceled:  Fires when the subscription cancel request is completed through the API without ?billingPeriod=0, or through the FastSpring App with the option to Deactivate at Next Period selected. (In this case, subscription.deactivated event would also fire later, on the deactivation date.)

Cancel Subscriptions Flow

 

Get Subscriptions

When working with subscriptions using the FastSpring API, you must have the unique subscription ID to perform any action against the subscription. You can obtain the subscription ID by subscribing to webhooks or using GET /subscriptions. Using GET /subscriptions returns a list of all active subscription IDs. 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 returns the details of the specific subscriptions. Issuing the GET/subscriptions/{id1}/entries request generates a response that includes all of the rebill transactions for the subscription.

Get Subscriptions Flow

Since each item in an order generates 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.

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.