/sessions

Last modified January 9, 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

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.

Read more about the Order Flow.

Creating a session

POST /sessions

Example 1: 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 2:  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
    }
  ]
}

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