FastSpring API

Last modified October 5, 2018

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

Table of Contents

What is the FastSpring API?

The FastSpring API is back-end service you can use to communicate with your FastSpring Store programatically, e.g. as an alternative to using the Dashboard.  This is an advanced feature that requires some basic understanding of HTTP communication methods; GET, POST and DELETE are the primary methods used to communicate with the API.

Although the structure of the JSON data sent and received using the API is very similar to webhooks, the difference is that with webhooks, FastSpring proactively sends you data about subscribed events in near-real time, as the events happen. You create and arrange hosting for a script that will parse these posts as they come in.  By contrast, using the FastSpring API, you initiate all communication with your FastSpring Store, on demand. You can request data from your Store using the GET method, and you can send data to your FastSpring Store (for example, creating a new product record) using the POST method. Using webhooks does not preclude the use of the API, nor does using the API prevent you from subscribing to and receiving webhook events. Indeed, one of the API endpoints (/events) is specifically designed to help you manage your webhook events.

Because it is a back-end service and does not have to interact with customers' Web browsers, using the API may be more secure compared to client-side methods of communicating with FastSpring, such as the Store Builder Library. (However, the Store Builder Library does offer enhanced security measures such as the secure payload, as well.)

Here are just a few practical examples of ways you might take advantage of the FastSpring API:

Description More Information
Creating a batch of numerous product records without using the Dashboard /products
Looking up a customer's account details in real-time, on demand /accounts
Validating a customer's access to your service based on order details /orders
Creating a custom order session for a specific customer that may override normal product pricing and pre-fill customer data /sessions
Retrieving product details (description, price, image, etc.) from your FastSpring Store in real-time to populate your own web pages /products

Note

If you would prefer a client-side method of communicating with your FastSpring Store and generating dynamic Web page content, check out the Store Builder Library.

Note

As the merchant and seller of record for all of the transactions we process, only FastSpring can collect customers' payment details (e.g. credit card numbers). Thus, in order to create new transactions via the FastSpring API, the customer must already have a payment method on file with FastSpring. Read more about creating orders for customers with payment methods on file here.


Accessing the API

Address of the FastSpring API

Make all requests to https://api.fastspring.com

Important

Ensure that the HTTP methods for all calls (e.g. "GET", "POST", or "DELETE") use uppercase letters. Use of lowercase letters (e.g. "get", "post" or "delete") may result in an error 404 response.

Note

We require TLS 1.2 (or better) encryption for all calls to the FastSpring API. TLS version 1.1 and earlier are not supported.

Note

The API requires a "User-Agent" header to be included in all requests. If this is not included, you may receive an error 401 when attempting to make API requests.


API Credentials and Authentication

FastSpring API credentials consist of a single username and password for your entire Store. The username and password are used for "Basic Authentication" when making requests to the API.

To Obtain Your API Credentials

  1. Log on to the Dashboard and navigate to Integrations > API Credentials. Initially, the only option on this page will be the CREATE command.

    Integrations menu
    API Credentials tab
    API Credentials tab with the CREATE button

  2. Click CREATE to generate your API Username and Password, which will be displayed when the page automatically refreshes.

    Example of the API Credentials tab after new credentials have been generated

  3. Make a note of the credentials and store them securely.

Important

The API credentials allow complete access to and control over your FastSpring Store. Treat them the same way you treat your own username and password for Dashboard.

Important

Be sure to store your API credentials in a location where you will be able to access them later.  You will not be able to view the password in the Dashboard again after you log off of your current Dashboard session. In subsequent sessions, the username will be displayed, but not the password. It is possible to reset the API credentials, but if you do so, bear in mind that any stored procedures or cron jobs you have that rely on API access will have to be updated immediately with the new credentials, or else the API requests will fail.



Data Types

When preparing your database structure for storing values obtained from FastSpring via our JSON payloads you might assume the following datatypes:

  • All "string" columns are VARCHAR 255, accordingly trimmed
  • Encoding is UTF-8
  • For numeric values (such as price or discount values) 2dp precision is expected ("2.00")


Available API Endpoints

Endpoint Description Functions
/accounts

Work with customer accounts and FastSpring-generated account IDs
  • Get one account
  • Get all accounts
  • Create an account
  • Update an existing account
  • Look up accounts by parameters
  • Get authenticated account management URLs
/coupons Work with promotional coupons and their customer-facing codes
  • Create a coupon
  • Update an existing coupon
  • Add coupon codes to a coupon
  • Retrieve coupon details
  • Get coupon codes assigned to a coupon
  • Delete coupon codes from a coupon
/events Retrieve unprocessed webhook events and mark events processed
  • Get processed or unprocessed webhook events matching specified parameters
/orders Work with order / transaction records
  • Get orders by ID
  • Get orders by product path
  • Get orders by date range
  • Create a new order and complete the charge
  • Update order tags and attributes
/products

Work with product records

  • Get one or more products

  • Get a list of all product IDs

  • Create one or more new products

  • Update one or more existing products
/returns Work with returns and refunds
  • Get one or more returns by ID
/sessions Create a pre-loaded cart session for a specific customer with a FastSpring-
generated account IDs; you can load the session in a Popup Storefront
or provide the customer with a link to the session via a Web Storefront
  • Create a pre-filled order session
/subscriptions Work with customers' recurring-billing subscription instances
  • Get all subscription instances
  • Get one or more specific subscription instances
  • Get subscription instance entries
  • Update existing subscription instances
  • Cancel subscription instances
  • Uncancel subscription instances prior to deactivation
  • Rebill managed subscription instances


Rate Limiting

In order to maintain a responsive user experience, FastSpring may impose request rate limits on API calls originating from individual accounts. In the event that the rate limit is met, the response to the API request will be an http 404 response code (though this may be improved soon).

Batch requests

If you need to make a large number of API requests in a very short time, such that you may encounter rate limits, consider using batch requests where possible. For example, when retrieving authenticated account management URLs, you can obtain URLs for multiple account IDs in a single request:  

GET /accounts/{id1}[,{id2},{id3},...]/authenticate

More information about this example can be found in our Knowledge Base article about the accounts endpoint.

Similar batch functionality is available for retrieving orders, products, returns and subscriptions.