/sessions

Last modified September 18, 2017

Sessions

Sessions are required to create an "order". The session might contain a customer information, products information and discounts. When you create a session via the API, the response from the API will include the session ID. You can then use that session ID to collect payment from the customer. The customer cannot change the details of the session.

Note

Sessions created via the /sessions endpoint are valid for 24 hours, after which they will expire.

Note

This requires an existing customer account. If your customer has purchased from you previously and you have obtained the customer's FastSpring-generated account ID, you can pass that into the POST. Otherwise, you need to pre-create an account with the customer's name and email address via the API as well - more information is available at /accounts.

Caution

Be sure the customer account includes the customer's country.  This information is required for certain non-credit card payment methods (e.g. PayPal), and transactions based on sessions could potentially fail if the country is not included in the customer's account.

Tip

One example of a way to take advantage of the /sessions API endpoint is to provide customers with a "name your price" or "pay what you want" option on your web pages. Simply design your web site to accept price data from your customers, and use the /sessions endpoint to create a session that overrides the products' default prices. Alternatively, this can also be done using a secure request via the Store Builder Library.

Read more about the Order Flow.

Creating a session

POST /sessions

Example 1: Creating a session without overriding any default attributes 

Request Example
{
   "account": "uKj7izONRfanVwBL9eiG_A",                                        // FastSpring-generated customer account ID (previously established via a prior order from this customer, or via the /accounts endpoint)
   "items": [
       {
           "product": "falcon",                                                // product path of the product(s) to be included in the order
           "quantity": 1                                                       // quantity of the current product to be included in the order
       }
   ]
}
Response Example
{
  "id": "FnE_y0t9R_WF5b2W0DI72Q",                                              // session ID to be used in customer-facing URL or fastspring.builder.checkout("sessionID");
  "currency": "USD",
  "expires": 1490109872476,
  "order": null,
  "account": "uKj7izONRfanVwBL9eiG_A",
  "subtotal": 9.95,
  "items": [
    {
      "product": "falcon",
      "quantity": 1
    }
  ]
}


Example 2: Overriding a product's default pricing

Request Example
{
   "account": "uKj7izONRfanVwBL9eiG_A",                                        // FastSpring-generated customer account ID (previously established via a prior order from this customer, or via the /accounts endpoint)
   "items": [
       {
           "product": "falcon",                                                // product path of the product(s) to be included in the order
           "quantity": 1,                                                      // quantity of the current product to be included in the order
           "pricing": {
               "price": {
                   "USD": 10.00                                                // other currencies supported by the Store may be specified
               }
           }
       }
   ]
}
Response Example
{
  "id": "Up_M3u20QA-fyeM2Sv-0uA",                                              // session ID to be used in customer-facing URL or fastspring.builder.checkout("sessionID");
  "currency": "USD",
  "expires": 1482355186169,
  "order": null,
  "account": "uKj7izONRfanVwBL9eiG_A",
  "subtotal": 10,
  "items": [
    {
      "product": "falcon",
      "quantity": 1
    }
  ]
}


Example 3:  Applying a coupon to an order

Request Example
{
   "account": "uKj7izONRfanVwBL9eiG_A",                                      // FastSpring-generated customer account ID (previously established via a prior order from this customer, or via the /accounts endpoint)
   "items": [
       {
           "product": "nest",                                                // product path of the product(s) to be included in the order
           "quantity": 2                                                     // quantity of the current product to be included in the order
       }
   ],
   "coupon": "0BXB6NMMCT"                                                    // coupon code (not coupon ID) to be applied to the order 
}
Response Example
{
  "id": "c7OY_bnCTSuUlwPHq1BMhg",                                            // session ID to be used in customer-facing URL or fastspring.builder.checkout("sessionID");
  "currency": "USD",
  "expires": 1482355423050,
  "order": null,
  "account": "uKj7izONRfanVwBL9eiG_A",
  "subtotal": 7.92,
  "items": [
    {
      "product": "nest",
      "quantity": 2
    }
  ]
}


Possible error responses

Error Response Example
Response
400
{
  "message": "Can not parse request body.",                                  // invalid or malformed JSON object in request
  "params": []
}

 
Response
400
{
  "message": "invalid",                                                      // request includes an invalid value
  "params": [
    "coupon"                                                                 // name of the value that is not valid (e.g. for an invalid coupon code)
  ]
}
 
 
Response
400
{  
   "message":"Item exists",                                                  // attempted to add the same product path twice in the same request
   "params":[  
      "falcon"                                                               // product path of duplicated item
   ]
}
 
 
Response
400
{
  "message": "Item not found",                                               // product path not found / invalid
  "params": [
    "falkon"                                                                 // path of the invalid / not found product
  ]
}


Response
400
{                                                                            
  "message": "required",                                                     // missing or invalid required parameter
  "params": [
    "account"                                                                // name of the missing or invalid parameter (account = account ID)
  ]
}


Deploying a Session for Payment via a Web Storefront

To have the customer purchase using the session via your Web Storefront, append /session/<sessionID> to the Storefront's Homepage URL and then provide the URL to the customer.

For example, if your Web Storefront's Homepage URL is https://furiousfalcon.onfastspring.com and your session ID is c7OY_bnCTSuUlwPHq1BMhg, the URL would be:

https://furiousfalcon.onfastspring.com/session/c7OY_bnCTSuUlwPHq1BMhg


Upon visiting the link, the customer will see your Web Storefront with the cart already defined based on the parameters you passed into the session. For example, if you passed in a coupon code as in example 2 above, the coupon will already be applied to the order:

Example of a Web Storefront with a pre-defined session loaded

Upon selecting a payment method, the information shown to (and required from) the customer will be limited based on the information already "known" to FastSpring for the account ID that you passed into the session. For example, the customer's name and email address will not be required.

Example of the Payment Information window of the Web Storefront after loading a pre-defined session

Deploying a Session for Payment via a Popup Storefront

To have the customer purchase using the session via your Popup Storefront, simply pass the session ID obtained in the API response into the fastspring.builder.checkout("<sessionID>") method.

For example, if your session ID is c7OY_bnCTSuUlwPHq1BMhg, the method would be fastspring.builder.checkout("c7OY_bnCTSuUlwPHq1BMhg").

Upon making the call in the customer's Web browser (e.g. on a page on your web site), the customer will see a normal Popup Storefront modal checkout window, but the information shown to (and required from) the customer will be limited based on the information already "known" to FastSpring for the account ID that you passed into the session. For example, the customer's name and email address will not be required.

Example of a Popup Storefront pre-loaded via a session