Collapse Menu
Docs Home
Extensibility Options
Contact Support

/sessions

Overview

This article provides information about the /sessions endpoint of the FastSpring API. You can use this endpoint to pre-populate an order with cart contents and customer information.

This article provides information about the /sessions endpoint of the FastSpring API. You can use this endpoint to pre-populate an order with cart contents and customer information.

 

Sessions

You can use the sessions endpoint to pre-populate an order with cart contents and customer information. The session might contain discounts, price overrides, custom tags, and more. When you create a session via the API, the response from the API includes 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. When the customer successfully makes payment via the session, the result is an order record.

 Note

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

 Note

Posts to the /sessions endpoint require 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. You can find more information at /accounts.

 Note

Each session or order can only contain a single occurrence of any given product or its product variations. For example, you cannot include a product and one of its variations in the same session. Likewise, you cannot include more than one variation of the same product in a single session. Either way, the result is an error 400 with the message "Item exists."

 Note

The recipient object used with the Store Builder Library session object and fastspring.builder.recognizeRecipients() method is not currently supported via the /sessions API endpoint. At the moment, it is not possible to pre-fill gift recipient information via the /sessions endpoint.

 Caution

Be sure the customer account includes the customer's country. The account country is required for certain non-credit card payment methods (e.g., PayPal). 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 "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, you can do this 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": "example-product-1",                        // 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": "example-product-1",
      "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": "example-product-1",                        // 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": "example-product-1",
      "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": "example-product-2",                          // 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": "example-product-2",
      "quantity": 2
    }
  ]
}

 

Example 4:  Applying a Product-Level Discount (Not a Coupon) to a Subscription Order for the Initial Transaction Only

Request Example
{  
  "account":"N8FjcSWcQNeYCc-suM1O8g",                  // FastSpring-generated customer account ID (previously established via a prior order from this customer, or via the /accounts endpoint)
  "items":[  
    {  
      "product":"example-monthly-subscription",        // 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":{  
        "renew":"auto",
        "interval":"month",
        "intervalLength":1,
        "intervalCount":3,
        "upcomingProduct":null,
        "quantityBehavior":"allow",
        "quantityDefault":1,
        "price":{  
          "USD":10.00
        },
        "quantityDiscounts":{  
          "1":                                         // this object indicates that the specified discount applies even when the quantity is one; additional discounts could be applied at other quantity levels
          {
            "USD":2
          }
        },
        "discountDuration":1                           // the discountDuration of 1 means the discount will only apply to the initial charge; you would enter 2 for the initial charge and first rebill, and so on
      }
    }
  ]
}
Response Example
{  
  "id":"qK_Xnc-kQHK_eYVZLlzAig",                       // session ID to be used in customer facing URL or fastspring.builder.checkout("sessionID")
  "currency":"USD",
  "expires":1558813994056,
  "order":null,
  "account":"N8FjcSWcQNeYCc-suM1O8g",
  "subtotal":8,
  "items":[  
    {  
      "product":"example-monthly-subscription",
      "quantity":1
    }
  ]
}

 

Example 5:  Specifying or Overriding a One-Time Setup Fee for a Subscription Product

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": "example-monthly-subscription",  // 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": {
              "setupFee": {                            // subscription one-time setup fee
                "title": {                             // customer-facing description of the one-time setup fee
                   "en": "Subscription Initiation Fee"
                },
                "price": {                             // amount of the one-time setup fee
                   "USD":10.00
                }
              }
           }
       }
   ]
}
Response Example
{
    "id": "-1sHIQliSQGKGvF6vJWb0g",
    "currency": "USD",
    "expires": 1572726026353,
    "order": null,
    "account": "uKj7izONRfanVwBL9eiG_A",
    "subtotal": 24.95,
    "items": [
        {
            "product": "example-monthly-subscription",
            "quantity": 1
        },
        {
            "product": "example-monthly-subscription.setupFee",
            "quantity": 1
        }
    ]
}

 

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; this includes product variations associated with a product already in the request (and vice versa)
   "params":[  
      "example-product-1"                                         // product path of duplicated item
   ]
}
 
 
Response
400
{
  "message": "Item not found",                         // product path not found / invalid
  "params": [
    "exampl-product-1"                                           // 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://yourexamplestore.onfastspring.com and your session ID is k5l1ezPuSBa_Mo7u1_RS1w, the URL would be:

https://yourexamplestore.onfastspring.com/session/k5l1ezPuSBa_Mo7u1_RS1w

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 3 above, the coupon will already be applied to the order:

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.

 

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 s9vP7-LmR3KJuAAAhjTYcw, the method would be fastspring.builder.checkout("s9vP7-LmR3KJuAAAhjTYcw").

Upon making the call in the customer's Web browser (e.g., on a page on your web site), the customer will see a standard Popup Storefront modal checkout window. However, 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.

Try FastSpring

Get a free account and see why FastSpring is the ecommerce partner of choice for software providers around the world. Try our full-service ecommerce solution today to unlock revenue growth for your online company.