Collapse Menu
Docs Home
Developer Tools
Contact Support

/sessions

Overview

Use the /sessions endpoint of the FastSpring API to pre-populate an order with cart contents and customer information.

A session may contain discounts, price overrides, custom tags, and more. When you create a session via the FastSpring API, the response from the API includes the session ID, which you can use to collect payment. A customer cannot change the details of the session. A successful payment via the session creates an order record.

Session Behavior

  • Expiration: Sessions created via the /sessions endpoint are valid for 24 hours by default and up to 7 days if specified. Use "expiration" with a value between 1 and 7 to represents the number of days to remain valid.
    • {
         "account": "igz8r5hcTWSKYygtly5zSQ",   
         "expiration": 7,            
         "items": [
             {
                 "product": "prime-sub",
                 "quantity": 1                           
             }
         ]
      }
  • Customer Accounts: 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. See /accounts.
  • Products Allowed: Each session or order can only contain a single occurrence of any given product or its product variations. If you include more than one variation of the same product in a single session, it will result in an error 400 with the message "Item exists."
  • Session Object: 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. It is not possible to pre-fill gift recipient information via the /sessions endpoint.
  • Customer Country: The account country is required for certain non-credit card payment methods so be sure the customer account includes the customer's country. Transactions based on sessions could fail if the country is not included in the customer's account.

An example to use the /sessions API endpoint is to provide customers with an option to pay what you want. Design your website to accept price data from your customers and use the /sessions endpoint to create a session that overrides the default prices. Alternatively, you can do this using a secure request via the Store Builder Library. Read more about the Order Flow.

Create a Session

POST /sessions
   

Example 1:  Create 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:  Override 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:  Apply 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:  Apply 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:  Specify or Overrid 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)
  ]
}

 

Deploy 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.

Deploy 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.