Billing API Summary

Many of the 3rd party apps available in BaseSpace perform processing-intensive operations that often cost the app developers money. In order to recoup some of the costs and to encourage a thriving app ecosystem, we are providing a way for users to pay for the services provided by the apps they use.

We have expanded the BaseSpace platform with the ability for apps to charge users for the service they're receiving in a secure and simple way. BaseSpace will manage all the billing infrastructure allowing you as an app developer to focus on continuously building out your apps without worrying about the complexities of billing.


All in-app purchases are performed using an Illumina currency called iCredits. Before a user can make any in-app purchases, they must add iCredits to their account by purchasing them through BaseSpace. 1 iCredit can be purchased at a rate of 1 USD.

Purchasable Products

You can configure one or more products that your application will offer for sale by going to the "Pricing" tab for your App. For each Product, you need to simply enter a description, an expiration time, and a price. Products may be purchased for a predetermined period of time, may unlock new features in the app, or may be charged based on the size of the files being analyzed. Products are very customizable, so you are free to set up your Products however you wish. Although you may change prices for your products later on, there may be some limitations for how often you may make pricing changes.

Revenue Sharing and Payouts

Payouts to app developers happen at a predetermined period, such as every 30 days, where they will get a payout in USD. The app developers get 70% of the total iCredit usage. The app developer also pays for the cost of usage (processing costs) and refunds. Illumina keeps 30% of the total usage. Illumina will not be passing on costs of usage in the initial billing rollout.

Issuing Refunds

There may be cases when your application has received iCredits but could not effectively deliver up to the user's expectations. This may be because the app encountered an error during processing, encountered or processed corrupted data, or simply because the user was unsatisfied with the results. In cases like these, we encourage apps to refund iCredits to the user.

Refunds may be provided via the API or, for native apps, automatically when the app fails. iCredits that were given to the application will then be refunded to the user. We have placed a 1 day limit on the length of time a refund may be performed from the time the purchase was made.

If the user would like a purchase to be refunded but the app provides no means for performing the refund or chooses not to, the user may contact Illumina support. Illumina has the right to decide to revoke billing rights of an application should this occur too frequently.

Supported Platforms

Billing is available for all types of apps for BaseSpace. Native, Web, Desktop, and Mobile apps all have the ability to charge the user for their services.

Keeping Track of Purchases

After selecting your App in the My App control panel, you will see the "Purchases" tab where you have access to a running log of purchases for that app. This will include purchases that were completed, cancelled, and refunded.

Avoid Redundant Purchases for Persistent Products

You can create Products that either have an expiration period or do not expire. Once the user has purchased this Product, they will not be able to purchase it again until the purchased product has expired. Currently a Persistent Product can expire after 7 days, 30 days, or never expire.

A user should not have to pay more than once for the same service, data analysis, or functionality to be made available. It is the app's responsibility to keep track of user purchases in order to avoid asking the user to make redundant purchases. Using the API, an App can determine if a User has previously purchased any persistent products.

Setup and Workflow summaries

The following section will cover the major steps required by the app in order to bill the user for the analysis.

Enabling Billing for an Application

Before Products or Purchases can be made, your account needs to have Billing enabled.

Every application will have Billing disabled by default. In order to see if your application has Billing enabled, simply go to the App Dashboard, click on your app, and click on the "Pricing" tab. If Billing is disabled, you will see the following:

Billing Disabled Example

To enable Billing, please send an email to with your Application Id, Company/Organization Name, and your BaseSpace UserName/Email Address to enable billing for your application.

Creating Products for an Application

Types of Products:

  • Persistent: A Product that either has an expiration period or does not expire. Once the user has purchased this Product, they will not be able to purchase it again until the purchased product has expired. Currently a Persistent Product can expire after 7 days, 30 days, or never expire.
  • Non-Persistent: A Product that expires immediately. A user can purchase this Product more than once

Creating Products:

After enabling Billing for your application, you can access the "Pricing" and "Purchases" sections of the App. Simply navigate to the App Dashboard, select your app, and you will see the following tabs, highlighted in red:

App Dashboard with Billing Tabs

Click on the "Pricing" tab. After doing so, you will see the following:

Pricing Tab

Now, to create a Product, just enter the information in the "Create A New Product" section and hit the green "Create" button. If the Product was successfully added, it will be displayed in the "Current Sellable Products" table.

Note: The description of your Product should give the User detailed information about the Product being purchased. A User will see the Name and Description of the Product during the transaction as well as on the App's page on BaseSpace (see the following)

App Details Page With Pricing

In this screenshot, the Description for the Product is "RNA-Seq 7-Day Subscription" and the Price is 12 iCredits.

Application Purchase History

An Application's purchase history can be found by going to the "Purchases" tab in the App's page. The purchase history shows a list of purchases with the Purchase Id.

The following is a screenshot of the purchase history for an application:

Purchase History

Lookup Previously Purchase Products

When an App is launched, it should determine which Products the User has purchased and which ones are still active. To do this, the GET: users/current/products API method should be used to list a User's purchased products, and to filter them by Product Id or by Tags. This is described in more detail in the Billing API Reference.

Initiating a Purchase

  1. Initiate a new purchase by calling POST:applications/{id}/purchases and by providing one or more products, a description of the purchase, and the current AppSession Id. The response will contain a purchase Id, a URI to the BaseSpace 'shopping cart' which can be found in the field HrefPurchaseDialog, and a RefundSecret which can be used if issuing a refund later.

  2. Direct the user to the URI from HrefPurchaseDialog where the user will complete the purchase. User will log in if necessary and will be presented with the list of products and overall price. If the user doesn't have sufficient balance then they will be asked to add credit first via a credit card. When the purchase completes, the user will be directed to the redirect_uri you've configured for your app. The redirect_uri will also contain the purchase Id.

  3. It is imperative to look up the purchase Status by calling GET: purchases/{id} to determine whether or not the user completed the purchase successfully. If it was completed, the Status of the Purchase is COMPLETED. If the user cancels the purchase or encounters an error during the process, the Status of the purchase will be set to ERRORED or CANCELLED respectively and the user will see an error message.

For more details, please refer to the Billing API Reference.

Issuing a Refund

  1. Ensure that a purchase is in a completed state by calling GET: purchases/{id}.
  2. Perform a call POST: purchases/{id}/refund. The RefundSecret you received when creating the purchase must be provided. A short RefundComment may be provided as well.

This is described in the Billing API Reference.