Subscription Integration

Last modified October 5, 2018

This article applies to Contextual Commerce. (Looking for Classic Commerce documentation?)

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 Vendor Management user interface.  The ability to update the subscription attributes such as quantity and upgrades/downgrades are available to the customer through the self service option. 

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 if how often future billing for the subscription will occur.  The subscription can be set to automatically rebill at specific interval by setting a recurring period.  If you prefer to rebill using another method in partnership with the FastSpring APIs or manually through Vendor Management, 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 automatically rebilled at the intervals specified in the product's subscription definition using the payment details entered during the original purchase. 
  • Managed - with managed subscriptions the rebills are considered "adhoc" and are triggered by through the API 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 under Orders and Subscriptions you can view all of the subscriptions

The subscription set up also provides options for automatic renewal of the subscription when the current subscription period ends.  The options allow you to always renew, ask the customer if they want to auto renew with the option to default the answer to yes or no, or the subscription must be manually renewed.  Subscriptions that automatically renew will use the customer's saved account payment information and the original subscription definition.  For example: if the subscription payments of $25 were due monthly for 12 months, the renewal will set up a new set of subscription payment series of $25 for 12 months.

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 /products endpoint 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 /subscriptions endpoint or the Dashboard 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 subscription instance is created with a unique identifier for each subscription item in the order.  All of a customer's subscriptions are maintained within the customer's account.  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 and renewals. 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 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's id to create the order.  This can be obtained through the account.created webhook or the /accounts 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 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 integrating with the webhook 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

New Subscription Flow Activty Diagram

 Active Subscriptions

Subscriptions that have a subscription instance and has not reached it's end date or been cancelled are considered an active subscription.  Once the charging event trigger has occurred on an active subscription both automated 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 manually charging through the Orders user interface.   The charging event trigger for an automated subscription is the payment due date.  Unlike  a managed subscription, an automated subscription is self-managing.  The price and recurring periods are based on the product at the time of purchase.  When an active subscription is changed, the changes only effect future subscription instances.  Historical instances are not automatically updated. 

At each charging event the subscription fee is automatically charged to the payment method on the customer's account.  Failure to charge the payment method on the customer's account 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:

  • Payment due reminder
  • Payment past due (series of up to 4 notifications at configurable intervals)
  • Payment charge failed 

Webhook vendor notifications that can fire for a subscription:

  • subscription.activated
  • subscription.updated
  • subscription.canceled
  • subscription.deactivated
  • subscription.charge.failed
  • subscription.charge.completed
  • subscription.payment.reminder
  • subscription.payment.overdue
  • refund.issued

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 payment method on the customer account.  If the payment method does not exist or is invalid, the subscription dunning 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 will fire.  This webhook is the only notification that will be provided when a subscription has reached it's end date.  The subscription.deactivated webhook will also fire when a subscription is cancelled immediately or is cancelled due to non-payment. 

 Subscription Charge Flow

  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 Vendor Management user interface or through the FastSpring API.   Subscription details can be obtained through the subscription.activated webhook 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

  Charge Managed Subscription Integration Diagram

Subscription Payment Notifications

There 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. 
  • Payment overdue - this notification series can be used to  inform your customers when their payment is past due.  There can be up to 4 steps in the series.  The first step is an automatic follow up.  You can set the intervals and actions for steps 2 and 3 and if you elect to use all 4 steps, the last step will deactivate the subscription 3 days after the previous step. 

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

Payment Reminder and Overdue Payment Process

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 the proration default through 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 identifier for the subscriptions that you are updating.  If needed, you can use the GET functions to obtain the subscription identifiers. 

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.   When creating your subscription products you can set the proration preference for "mid-flight" changes.  This setting can be overridden in the API when a change is made to a specific subscription instance by sending the prorate option.   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.

Changes made to a subscription will only apply to the current (if immediate is indicated) and future subscription instance periods.   

 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 to the main subscription product.  Vendor Management should be used to update add-on products.    
  • 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 a historical date. It can only be changed to tomorrow and future.
  • Payment details are part of the customer account and cannot be updated through /subscriptions.  Customers should use the self-service account management feature to update their payment information. 
  • Updates that result in a payment due or refund for the current period will result in a charge or refund posted to the payment method of record on the customer's account. 
    • A charge will fire the subscription.charged webhook.
    • A refund will fire the refund.created webhook.   

Update Subscriptions Integration Diagram

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 webhooks can file when a subscription is canceled:

  • subscription.deactivated - will fire when a subscription is canceled immediately through the API or Vendor Management user interface.
  • subscription.canceled - will fire when the subscription cancel request is completed through the API or Vendor Management user interface.
 Cancel Subscriptions Flow

Cancel Subscription Flow

Get Subscriptions

When working with subscriptions you must have the unique subscription identifier in order to perform any action against the subscription.  You can obtain the subscription identifier 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 pages using the page and  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 charging periods for the subscription.  

 Get Subscriptions Flow

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

Get Subscriptions Integration Diagram