BaseSpace Billing REST API Reference

The BaseSpace Billing API is used to charge users for the services that the app provides.


BaseSpace REST API Reference

The BaseSpace Billing REST API follow much of the same conventions as the BaseSpace REST API. Please refer to the BaseSpace REST API Reference for information about URI Format for requests, Individual and Collection Resource Requests, and Common Response Elements.


Enabling Billing for an Application

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

To Enable Billing, please refer to the Billing API Summary.


Purchases

After creating Products for your app in the App Pricing tab, you will be able to create Purchases. A Purchase occurs when an app charges a user. The user then has the option to accept or reject the Purchase. Each Purchase has a unique Id. Purchases may contain multiple Products and Quantities for each of those Products. The purchase history for an application can be found in the "Purchases" tab in the App Dashboard.

Response Elements:

  • Id: The Purchase Id
  • Status: The status of the Purchase, this depends on whether the user has or has not accepted the Purchase
    • PENDING: The purchase is pending
    • CANCELLED: The user cancelled the purchase when directed to the shopping cart
    • ERRORED: An error occurred during the Purchase
    • COMPLETED: The purchase was completed and processed
  • RefundStatus: The refund status of this purchase.
    • NOTREFUNDED: This Purchase has not yet been refunded
    • COMPLETED: This Purchase has been refunded
  • DateCreated: The date on which the Purchase was created.
  • DateUpdated: The last date that the Purchase was updated, generally when the status was updated.
  • InvoiceNumber: The invoice number for this transaction.
  • Amount: The total cost of the Purchase before tax
  • AmountOfTax: The cost of tax on this Purchase
  • AmountTotal: The total cost of the Purchase after tax
  • Products[]: An array of the Products that were part of this Purchase. Note: multiple Products for the same app may be purchased in multiple quantities
    • Id: The Id of the Product
    • Name: The Name of the Product
    • Price: The Price of the Product
    • Quantity: The Quantity of the Product. Note: Decimal quantities are supported.
    • PersistenceStatus: Shows whether or not this product is persistent.
      • NOPERSISTENCE: This is not a persistent product
      • ACTIVE: The persistent product is still active on this purchase and this product cannot be purchased again by the user
      • EXPIRED: The persistent product has expired and will need to be purchased again by the user
    • Tags[]: An array of tags associated with this Product. An app can use GET: users/current/products?Tags= to filter out the user's Products by these Tags.
  • PurchaseType: The type of purchase that was made.
    • Product: An app product was purchased
  • AppSession: The AppSession with which this Purchase is associated.
    • Id: The Id of the AppSession
    • Name: The Name of the AppSession
  • User: The user that will be charged for this Purchase
    • Id: The Id of the user
    • Name: The Name of the user
  • Application: The application that created this Purchase
    • Id: The Id of the application in BaseSpace
    • Name: The Name of the application
    • CompanyName: The name of the Company associated with this

POST: purchases

Initiate a purchase for the user. Use this method to begin the process of charging a user for the application. When creating a purchase, keep your access_token and RefundSecret for your records, your app will need these in order to issue a Refund on a Purchase.

Note: Users have 60 minutes to accept a Purchase before it is expired.

Request Header Parameters:

  • Content-Type: Should always be application/json for this request

  • x-access-token: The BaseSpace access_token that was returned from user authorization

Request Form Parameters:

  • Products[]: An array of the Products that are part of this Purchase.
    • Id: The Id of the Product
    • Quantity: The Quantity of the Product
    • Tags[]: Any Tags that you would like to associate with this Product. You can organize and uniquely tag all of your Products, this will allow you to search through a User's purchase products by filtering with a Tag.
  • AppSessionId: The Id of the AppSession that this Purchase is associated with.

Response Elements:

  • HrefPurchaseDialog: The url to direct the user to in order to purchase the product(s)

  • RefundSecret: The secret key that will be used in order to refund this purchase to the user

Example:

To create a new purchase for the current user (meaning that the app will charge the user) for Products with Ids using cURL:

curl -v \
-H "Content-Type: application/json" \
-H "x-access-token:{access_token}" \
-X POST -d '{ "Products" : [{"Id": "2c92c0f83cf64298013d404e9d19182d", "Quantity": "1", "Tags" : ["unique_tag_1"]}, {"Id": "2c92c0f83d3c4f06013d4051089e570b", "Quantity": "3", "Tags" : ["unique_tag_2"]} ] "AppSessionId" : "{id}"}' \
https://store.cloud-hoth.illumina.com/v1pre3/purchases

The Response will be a 201 Created with the newly created Purchase's information.

{
    "Response": {
        "Id": "5632731c78c1401cb18c9065b044b284",
        "Status": "PENDING",
        "RefundStatus": "NOTREFUNDED",
        "DateCreated": "2013-04-12T16:27:23.5453490Z",
        "DateUpdated": "2013-04-12T16:28:00.0593490Z",
        "InvoiceNumber": "INV00017679",
        "Amount": 12780,
        "AmountOfTax": 0,
        "AmountTotal": 12780,
        "Products": [
            {
                "Id": "2c92c0f83cf64298013d404e9d19182d",
                "Name": "My widget",
                "Quantity": 1,
                "PersistenceStatus": "NOPERSISTENCE",
                "Price": 420,
                "Tags": ["unique_tag_1"]
            },
            {
                "Id": "2c92c0f83d3c4f06013d4051089e570b",
                "Name": "Another widget",
                "Quantity": 3,
                "PersistenceStatus": "NOPERSISTENCE",
                "Price": 4120,
                "Tags": ["unique_tag_2"]
            }
        ],
        "PurchaseType": "product",
        "AppSession": {
            "Id": "959f4d6949fa4b36bbc9e03c948cdf67",
            "Name": "BaseSpace Automation Test"
        },
        "User": {
            "Id": "20020",
            "Name": "Jane Doe"
        },
        "Application": {
            "Id": "38038",
            "Name": "BaseSpaceTest",
            "CompanyName": "Illumina"
        },
        "RefundSecret": "c447766035c64ec4a74806387b293c54",
        "HrefPurchaseDialog": "https://store.cloud-hoth.illumina.com/applications/07f177c0e9a94bd58cd6321323ebf886/purchases",
    },
    "ResponseStatus": {},
    "Notifications": []
}

Before directing a user to the HrefPurchaseDialog, ensure that the Purchase Id is saved to verify the Purchase.

The app will then direct the user to the HrefPurchaseDialog where the user will be taken to a page to confirm the transaction and purchase the product.

Once the user has completed their purchase, they will automatically be redirected back to the application. In addition, the redirect will contain the purchase Id as a query parameter.

Here is an example of a successful purchase redirect:

http://uri.to.your.application?action=purchase&purchaseid=66d1ae67c4ac49928dbd90006151ccbd

Post-Purchase Redirect Query Parameters:

After the user has gone through the Purchase process, regardless of the outcome of the Purchase, the user is taken to a purchase status page and can then choose to return to the app. The status can be cancelled, errored, or successful. The purchase Id is returned as a URL Query Parameter to the application's redirect_uri if the user chooses this option. The application should then use the Purchase id with the GET: purchases/{id} method to obtain more information about the Purchase.

The application should ensure that the Purchase Id that was created is the same as the one that was returned here. Then, the application can use the Purchase Id to determine the Status and to see any errors that may have occurred.

The application must use the GET: purchases/{id} method to determine the current status of the Purchase. If the Status of the Purchase is COMPLETED, the Purchase transaction was processed. The status will be PENDING if the user has not yet accepted the Purchase. The status will be ERRORED if an error was encountered during the purchase transaction. The status will be CANCELLED if the user decided to cancel the purchase transaction.


GET: purchases/{id}

Retrieve a specific purchase by its Id. You will only receive a response if you are the app owner or the user of the purchase.

Example:

To retrieve a Purchase with Id 847c5437e00a4f5d8fd8027f1df3ec07:

GET https://store.cloud-hoth.illumina.com/v1pre3/purchases/847c5437e00a4f5d8fd8027f1df3ec07
{
    "Response": {
        "Id": "5632731c78c1401cb18c9065b044b284",
        "Status": "COMPLETED",
        "RefundStatus": "NOTREFUNDED",
        "DateCreated": "2013-04-12T16:27:23.5453490Z",
        "DateUpdated": "2013-04-12T16:28:00.0593490Z",
        "InvoiceNumber": "INV00017679",
        "Amount": 12780,
        "AmountOfTax": 0,
        "AmountTotal": 12780,
        "Products": [
            {
                "Id": "2c92c0f83cf64298013d404e9d19182d",
                "Name": "My widget",
                "Quantity": 1,
                "PersistenceStatus": "NOPERSISTENCE",
                "Price": 420,
                "Tags": ["unique_tag_1"]
            },
            {
                "Id": "2c92c0f83d3c4f06013d4051089e570b",
                "Name": "Another widget",
                "Quantity": 3,
                "PersistenceStatus": "NOPERSISTENCE",
                "Price": 4120,
                "Tags": ["unique_tag_2"]
            }
        ],
        "PurchaseType": "product",
        "AppSession": {
            "Id": "959f4d6949fa4b36bbc9e03c948cdf67",
            "Name": "BaseSpace Automation Test"
        },
        "User": {
            "Id": "20020",
            "Name": "Jane Doe"
        },
        "Application": {
            "Id": "38038",
            "Name": "BaseSpace Automation Test",
            "CompanyName": "Illumina"
        }
    },
    "ResponseStatus": {},
    "Notifications": []
}

If there was an error during the Purchase, the Purchase Status will be set to ERRORED. The status will be CANCELLED if the user decided to cancel the purchase transaction.


Products

A Product is an item that is purchased by a User. A user may be charged for a Product at the application's discretion. A Product contains the following information:

  • Id: The Id of the Product, this is found in the Products table in the Pricing page of the App Dashboard
  • Name: The Name of the Product. The User will see this on their receipt, it should give information about what is being purchased.
  • Price: The Price of the Product
  • Quantity: The Quantity of the Product that can be purchased. Note:Decimal quantities are supported.
  • PersistenceStatus: Shows whether or not this product is persistent.
    • NOPERSISTENCE: This is not a persistent product
    • ACTIVE: The persistent product is still active on this purchase and this product cannot be purchased again by the user
    • EXPIRED: The persistent product has expired and will need to be purchased again by the user

GET: users/current/products

Returns a list of Products that the user has purchased.

Query Parameters:

  • Tags: A comma-separated list of tags associated with this Product. This will allow you to search through a User's purchase products by filtering with a Tag.
  • ProductIds: A comma-separated list, allows filtering by purchased Product Id.

Response Elements:

  • PurchaseId: The Id of the Purchase transaction where this Product was purchased
  • DatePurchased: The date this Product was purchased by the user
  • Id: The Id of the Product
  • Name: The Name of the Product
  • Price: The Price of the Product
  • Quantity: The Quantity of the Product. Note: Decimal quantities are supported.
  • PersistenceStatus: Shows whether or not this product is persistent.
    • NOPERSISTENCE: This is not a persistent product
    • ACTIVE: The persistent product is still active on this purchase and this product cannot be purchased again by the user
    • EXPIRED: The persistent product has expired and will need to be purchased again by the user
  • Tags[]: An array of tags associated with this Product. An app can use GET: users/current/products?Tags= to filter out the user's Products by these Tags. This is a comma-separated list, which is set by the app when the purchase is created.
  • ProductIds: A comma-separated list, allows filtering by purchased Product Id.

Example:

To retrieve all purchased Products for the current user:

GET store.cloud-hoth.illumina.com/v1pre3/users/current/products?ProductId=2c92a0fb3dfca71e013e18fded36296f

{
    "Response": {
        "Items": [
            {
                "PurchaseId": "6e49c0e38575457da49ea5cd5b83907f",
                "DatePurchased": "2013-04-17T17:30:49.0350098Z",
                "Id": "2c92a0fb3dfca71e013e18fded36296f",
                "Name": "Test Product 1",
                "Quantity": 1,
                "PersistenceStatus": "NOPERSISTENCE",
                "Price": 1,
                "Tags": []
            }
        ],
        "DisplayedCount": 1,
        "TotalCount": 1,
        "Offset": 0,
        "Limit": 0
    },
    "ResponseStatus": {},
    "Notifications": []
}

Applications

Applications in the BaseSpace Billing API have the same Id as Applications in the BaseSpace REST API. The Applications API in the Billing API will contain information about the Products and Purchases for an Application.

GET: applications/id

Returns the application's pricing information

Response Elements:

  • DateCreated: The date this Application was enabled for billing
  • DateUpdated: The date this Application's pricing information was updated
  • Products: A collection of Products for this application
    • Id: The Id of the Product
    • Name: The name of the Product
    • Id: The price of the Product in BaseSpace iCredits
    • PersistenceDays: The number of days that this Product will persist after it has been purchased, after this time it must be purchased again.
    • Description: The description of the Product
    • DateCreated: The date this Product was created
    • DateUpdated: The date this Product was last updated
  • Id: The Id of the Application, this will be the same as the Application's Id in the BaseSpace REST API
  • Name: The name of the Application
  • CompanyName: The name of the company that owns this Application

Example:

To retrieve pricing information about application with id 4004:

GET https://store.cloud-hoth.illumina.com/v1pre3/applications/4004

{
    Response: {
    DateCreated: "2013-05-22T18:40:20.0000000Z",
    DateUpdated: "2013-05-22T18:40:20.0000000Z",
    Products: [
        {
            Id: "2c92c0f93ecaad62013ecd9e99c54c16",
            Name: "Product 1",
            Price: 1,
            PersistenceDays: 0,
            Description: "Expires After Use",
            DateCreated: "2013-05-22T19:02:03.0000000Z",
            DateUpdated: "2013-05-22T19:02:03.0000000Z"
        },
        {
            Id: "2c92c0f93ecaad62013ecd9fd5184c67",
            Name: "Product 3",
            Price: 1,
            PersistenceDays: 0,
            Description: "Expires After 7 Days",
            DateCreated: "2013-05-22T19:03:24.0000000Z",
            DateUpdated: "2013-05-22T19:03:24.0000000Z"
        },
        {
            Id: "2c92c0f93ecaad62013ecda088b84c7c",
            Name: "Product 5",
            Price: 1,
            PersistenceDays: 0,
            Description: "Does Not Expire",
            DateCreated: "2013-05-22T19:04:10.0000000Z",
            DateUpdated: "2013-05-22T19:04:10.0000000Z"
        },
        {
            Id: "2c92c0f93ecaad65013ecda0327948d9",
            Name: "Product 4",
            Price: 1,
            PersistenceDays: 0,
            Description: "Expires After 30 Days",
            DateCreated: "2013-05-22T19:03:48.0000000Z",
            DateUpdated: "2013-05-22T19:03:48.0000000Z"
        }
    ],
    Id: "4004",
    Name: "Example Application",
    CompanyName: "Illumina"
    },
    ResponseStatus: { },
    Notifications: [ ]
}

GET: applications/id/purchases

Returns the list of Purchases made for an Application

Response Elements:

  • Items: An array of Purchases for this Application
    • Id: The Purchase Id
    • Status: The status of the Purchase, this depends on whether the user has or has not accepted the Purchase
      • PENDING: The purchase is pending
      • CANCELLED: The user cancelled the purchase when directed to the shopping cart
      • ERRORED: An error occurred during the Purchase
      • COMPLETED: The purchase was completed and processed
    • RefundStatus: The refund status of this purchase.
      • NOTREFUNDED: This Purchase has not yet been refunded
      • COMPLETED: This Purchase has been refunded
    • DateCreated: The date on which the Purchase was created.
    • DateUpdated: The last date that the Purchase was updated, generally when the status was updated.
    • InvoiceNumber: The invoice number for this transaction.
    • Amount: The total cost of the Purchase before tax
    • AmountOfTax: The cost of tax on this Purchase
    • AmountTotal: The total cost of the Purchase after tax
    • Products[]: An array of the Products that were part of this Purchase. Note: multiple Products for the same app may be purchased in multiple quantities
      • Id: The Id of the Product
      • Name: The Name of the Product
      • Price: The Price of the Product
      • Quantity: The Quantity of the Product. Note: Decimal quantities are supported.
      • PersistenceStatus: Shows whether or not this product is persistent.
        • NOPERSISTENCE: This is not a persistent product
        • ACTIVE: The persistent product is still active on this purchase and this product cannot be purchased again by the user
        • EXPIRED: The persistent product has expired and will need to be purchased again by the user
      • Tags[]: An array of tags associated with this Product. An app can use GET: users/current/products?Tags= to filter out the user's Products by these Tags.
    • PurchaseType: The type of purchase that was made.
      • Product: An app product was purchased
    • AppSession: The AppSession with which this Purchase is associated.
      • Id: The Id of the AppSession
      • Name: The Name of the AppSession
    • User: The user that will be charged for this Purchase
      • Id: The Id of the user
      • Name: The Name of the user
    • Application: The application that created this Purchase
      • Id: The Id of the application in BaseSpace
      • Name: The Name of the application
      • CompanyName: The name of the Company associated with this

Example:

To retrieve list of Purchases for an Application with Id 4004:

GET https://store.cloud-hoth.illumina.com/v1pre3/applications/4004

{
    Response: {
        Items: [
            {
                Id: "d2b27c1836ce48d6a27cce9ebe37da7a",
                Status: "COMPLETED",
                RefundStatus: "NOTREFUNDED",
                DateCreated: "2013-05-22T20:56:10.0350000Z",
                DateUpdated: "2013-05-22T20:53:20.6479701Z",
                InvoiceNumber: "INV00011112",
                Amount: 1,
                AmountOfTax: 0,
                AmountTotal: 1,
                Products: [
                    {
                        Id: "2c92c0f93ecaad62013ecd9e99c54c16",
                        Name: "Product 1",
                        Quantity: 1,
                        PersistenceStatus: "NOPERSISTENCE",
                        Price: 1,
                        Tags: [ ]
                    }
                ],
                PurchaseType: "product",
                AppSession: {
                    Id: "a47f22c5c86d43cf82375ea2cac786d2",
                    Name: "Example AppSession"
                },
                User: {
                    Id: "17017",
                    Name: "John Doe"
                },
                Application: {
                    Id: "4004",
                    Name: "Example Application",
                    CompanyName: "Illumina"
                }
            },
            {
                Id: "9c186c7546434217aefed89a3d7da7ed",
                Status: "COMPLETED",
                RefundStatus: "NOTREFUNDED",
                DateCreated: "2013-05-22T20:55:10.7520000Z",
                DateUpdated: "2013-05-22T20:52:21.3519350Z",
                InvoiceNumber: "INV00031840",
                Amount: 1,
                AmountOfTax: 0,
                AmountTotal: 1,
                Products: [
                    {
                        Id: "2c92c0f93ecaad62013ecd9e99c54c16",
                        Name: "Product 1",
                        Quantity: 1,
                        PersistenceStatus: "NOPERSISTENCE",
                        Price: 1,
                        Tags: [ ]
                    }
                ],
                PurchaseType: "product",
                AppSession: {
                    Id: "342b6bc13fd6498f8c0051b33091d8ca",
                    Name: "Example AppSession"
                },
                User: {
                    Id: "17017",
                    Name: "John Doe"
                },
                Application: {
                    Id: "4004",
                    Name: "Example Application",
                    CompanyName: "Illumina"
                }
            }
        ],
        DisplayedCount: 2,
        TotalCount: 2,
        Offset: 0,
        Limit: 0
    },
    ResponseStatus: { },
    Notifications: [ ]
}

Refunds

An app may refund an app purchase to a user. This will restore the iCredits taken from the user's account and remove that credit from the app.

POST: purchases/{id}/refund

To refund this purchase and give the user their iCredits back.

Request Form Parameters:

  • RefundSecret: The RefundSecret provided in the Response from the POST: purchases request
  • Comment: An optional comment can be added for this refund

Request Header Parameters:

  • x-access-token: The BaseSpace access_token that was returned from user authorization when the purchase was made. You must use the same access token used with the purchase.

Response Elements:

  • DateRefunded: The date on which this refund was created
  • UserRefundedBy: The user for whom this refund was processed
  • RefundComment: A comment on the refund, provided by the app

Example:

To refund purchase id 2850eb5695a7463a971b947d0fb3d249 using cURL:

curl -v \
-H "x-access-token:{access_token}" \
-X POST \
-d "RefundSecret=8a10a48cde5648c38842d06d3fc42f86" \
-d "Comment=App failed during RNA-Seq analysis" \
https://store.cloud-hoth.illumina.com/v1pre3/purchases/2850eb5695a7463a971b947d0fb3d249/refund

{
"Response": {
    "Id": "2850eb5695a7463a971b947d0fb3d249",
    "Status": "COMPLETED",
    "RefundStatus": "COMPLETED",
    "DateCreated": "2013-03-20T18:16:51.2918342Z",
    "DateUpdated": "0001-01-01T00:00:00.0000000",
    "InvoiceNumber": "INV00011034",
    "Amount": 12780,
    "AmountOfTax": 0,
    "AmountTotal": 12780,
    "Products": [
            {
                "Id": "2c92c0f83cf64298013d404e9d19182d",
                "Name": "My widget",
                "Quantity": 1,
                "PersistenceStatus": "NOPERSISTENCE",
                "Price": 420,
                "Tags": ["unique_tag_1"]
            },
            {
                "Id": "2c92c0f83d3c4f06013d4051089e570b",
                "Name": "Another widget",
                "Quantity": 3,
                "PersistenceStatus": "NOPERSISTENCE",
                "Price": 4120,
                "Tags": ["unique_tag_2"]
            }
        ],
    "PurchaseType": "product",
    "AppSession": {
        "Id": "959f4d6949fa4b36bbc9e03c948cdf67",
        "Name": "BaseSpace Automation Test"
    },
    "User": {
        "Id": "20020",
        "Name": "Jane Doe"
    },
    "Application": {
        "Id": "38038",
        "Name": "BaseSpace Test",
        "CompanyName": "Illumina"
    },
    "DateRefunded": "2013-03-20T18:18:55.0631245Z",
    "UserRefundedBy": {
        "Id": "2002",
        "Name": "John Doe"
    },
    "RefundComment": "App failed during RNA-Seq analysis",
},
"ResponseStatus": {},
"Notifications": []

}