Unlike Quotes or Custom Orders, custom sessions are point in time order sessions(aka custom carts) that can be accessed by a session URL (returned in this API call response) specifically built for the purchaser, which can be sent to the buyer to complete a purchase (these sessions may be formed beforehand or on the fly depending on your workflow). Sessions are kept alive for 24 hours to provide sufficient time to complete purchase.
A session can be created with known account identifier or by passing a contact information block (which creates a unique account id before creating the session).
Once a session is created and sent to the purchaser, they have limited fields to fill in to complete the order.
Unlike custom orders or quotes, these sessions are not searchable under any filter on FastSpring App and it is up to the API caller to track what happened to that session.
Create a custom order session with single product and no overrides
{
"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", // 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 the price or attach coupon on the session, use contact block to create new account for the session
// Using contact block in lieu of known account ID
{
"contact": {
"first":"John",
"last":"Doe",
"email":"[email protected]", // If an account already exists with email, it will be latched onto and update
"company":"String", // optional
"phone":"String" // optional
},
"language":"en", //ISO valid language code
"country":"US", //ISO valid country code
"lookup":{ //optional
"custom":"customKey" //a-zA-Z0-9_- String with length greater than or equal to 4 (Alphanumeric unique lookup phrase for searching account)
},
"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 needed if overriding catalog price
"price": {
"USD": 7.95 // other currencies supported by the Store may be specified
}
}
}
]
}
{
"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" // valid coupon code (not coupon ID) to be applied to the order
}
Update Order session custom tags and product custom attributes on the items in the order
- Order tags can be key-value pairs of any information associated the order (these can also be passed in FastSpring Store Builder Library sourced order sessions)
- Product custom attributes are key-value pairs associated with the order line item's products in the order
A more complex example where we add 2 products to custom session, then add order tags and custom attributes for each product, also apply arbitrary discount on one.
{
"account": "N8FjcSWcQNeYCc-suM1O8g", // FastSpring-generated known customer account ID (previously established via a prior order from this customer, or via the /accounts endpoint) - Alternately you can use contact block
"tags":
{
"TagKey1": "TagValue1", // order tag to be added
"TagKey2": "TagValue2" // order tag to be added
},
"items": [
{
"product": "product-path", // Catalog product path of the product in cart/session
"attributes": {
"AttributeKey1": "AttributeValue1", // product attribute to be added
"AttributeKey2": "AttributeValue2" // product attribute to be added
}
},{
"product":"some-monthly-subscription", // catalog product-path of second item in cart/session whose pricing is overridden
"quantity":1,
"pricing":{
"trial":0, // days
"renew":"auto", // or "manual", "opt-auto", "opt-manual"
"interval":"month", // or "adhoc", "day", "week", "year"
"intervalLength":1, // required if "intervral" is specified and is not "adhoc"
"quantityBehavior":"allow", // or "lock" or "hide"
"quantityDefault":1,
"price":{
"USD":14.95, // Dynamically change the price to something other than catalog price
"EUR":10.99
},
"discount":{ // Dynamically inserted discount (not in catalog)
"type":"percent",
"percentage":10,
"duration": 6 // 6 periods get 10% off
}
},
"attributes":{
"ATTRIBUTE1":"value1" // optional custom product-level attributes for second product in session
}
}
]