Sessions in the FastSpring API are point-in-time order sessions, or custom carts, that can be accessed by a session URL. FastSpring returns the URL as a response when you call the /sessions endpoint.

You can then send the URL to a buyer so that they can complete a purchase. FastSpring keeps the session alive for 24 hours.

You can create a session with either a known account identifier or by passing a contact information block, which creates an account ID before generating the session.

After you create a session and send it to a buyer, the buyer has to fill in a number of fields to complete the order.

Unlike custom orders or quotes, sessions you create with the /sessions aren't indexed or searchable in the FastSpring app.

Create a custom order session with a single product

This example creates a custom order session for a single product using an account ID:

{
   "account": "uKj7izONRfanVwBL9eiG_A",   // FastSpring-generated customer account ID (established from a prior order from this customer, or by the /accounts endpoint)
   "items": [
       {
           "product": "falcon",           // Catalog 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
       }
   ]
}

Override a price and attach a session coupon

This request creates a session that overrides a product's price, using a contact block instead of a known account ID:

{
   "contact": { 
      "first":"John",
      "last":"Doe",     
      "email":"[email protected]",  // If an account already exists with this email, FastSpring will associate it with this session, and, if necessary, update it.
      "company":"String",       			// optional
      "phone":"String",         			// optional
      "country":"US",              		// ISO-valid country code
      "language":"en",             		// ISO-valid language code
   },
   "lookup":{                     		// optional
      "custom":"customKey"            // a-zA-Z0-9_- String with a length greater than or equal to 4 (an alphanumeric-unique lookup phrase for searching for accounts)
   },  
   "items": [
       {
           "product": "falcon",       // Catalog 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": {               // Only required if overriding catalog price
               "price": {
                   "USD": 7.95        // You can also specify other store-supported currencies.
               }
           }
       }
   ]
}

And this request applies a coupon code to the session's order:

{
   "account": "uKj7izONRfanVwBL9eiG_A",    // FastSpring-generated customer account ID (established from a prior order from this customer, or by 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"                  // Valid coupon code (not coupon ID) that gets applied to the order
}

Update order session custom tags and product attributes

You can add more information to your session by using order tags and custom attributes:

Order tags are key-value pairs that represent any information associated with the order. You can also pass order tags in with FastSpring Store Builder Library sourced order sessions).
Product custom attributes are key-value pairs associated with the order line item's products.

The following sample request combines these options:

The custom session request contains two products, one of which is a subscription.
Each product contains order tags and custom attributes.
Finally, the session has a discount applied to it.

{
   "account": "N8FjcSWcQNeYCc-suM1O8g",            // FastSpring-generated customer account ID (established from a prior order from this customer, or by the /accounts endpoint)
   "tags":
   {
        "TagKey1": "TagValue1",                   // Order tag 
        "TagKey2": "TagValue2"                    // Order tag
   },
   "items": [
     {
       "product": "product-path",                 // Catalog product path of the product in cart/session
       "attributes": {
         "AttributeKey1": "AttributeValue1",      // Product attribute 
         "AttributeKey2": "AttributeValue2"       // Product attribute 
       }
     },{ 
       "product":"some-monthly-subscription",     // Catalog product-path of the second item in cart/session, with price overridden
       "quantity":1,
       "pricing":{
          "trial":0,                              // In days
          "renew":"auto",                         // Other options include "manual", "opt-auto", "opt-manual"
          "interval":"month",                     // Other options include "adhoc", "day", "week", "year"
          "intervalLength":1,                     // Required if "interval" is specified and is not "adhoc"
          "quantityBehavior":"allow",             // Other options include "lock" or "hide"
          "quantityDefault":1,
          "price": {
             "USD": 14.95,
             "EUR": 10.99
          },
          "discountType": "percent", // "Percent" or "amount"
          "discountDuration": 2,
          "quantityDiscounts": {
            "1": 50.0 // Percent if type = percent; "1": {"USD": 0.00} // if type = amount
          }
       },
       "attributes": {
          "ATTRIBUTE1": "value1"
       }
     }
   ]

Working with trial subscriptions

FastSpring offers three trial subscription types: free trials without a payment method, free trials with a payment method, and paid trials.

When you create a session with a subscription product, you can apply additional attributes to the pricing object that override catalog settings.

By setting trial in the pricing object to greater than 0, you can configure the trial subscription type and discounts (for paid trials), as in the following examples:

"pricing": {
    "trial": 7,            				 // Required; specifies the duration of the trial period in days; must be greater than 0
    "paymentCollected": true,      // `True` or `false`; optional to override trial settings when `trial` is greater than 0 days
    "paidTrial": false,            // `True` or `false`; specifies whether the trial period is paid or free
    "trialPrice": {                // Required if `paidTrial` is `true`; otherwise it will be ignored
        "USD": 5,
        "EUR": 4
    }
}

"pricing":{
        "trial":7,                              
        "paymentCollected": false,   
        "paidTrial":false                                  
        }

"pricing":{
        "trial":7,                              
        "paymentCollected": true,               
        "paidTrial":false                      
        }

"pricing": {
    "trial": 7,                             
    "paymentCollected": true,               
    "paidTrial": true,                      
    "trialPrice": {                 // Applies a discount to the trial period price
        "USD": 5,
        "EUR": 4
    }
}
// This paid trial has a discounted price applied to it. 
// Once the trial period is over, the full price gets charged on rebill.

If you don't add any of these attributes to the subscription trial, the trial will retain its original catalog attributes.

Default behaviors

Keep the following in mind as you work with the /sessions endpoint:

Include the country field in the contact object for new buyers; if this field is missing, the system will default to the United States and USD as currency. For known users, the storefront will redirect to the account's registered country.
Session currency; the currency you specify in the request payload gets localized to match the session country's currency. For known buyers, the session currency will match the registered country currency. For new buyers, the currency gets based on the country you specify in the payload (for example, USD would convert to EUR for users in the Netherlands).