Methods

Use JavaScript to initiate a behavior against the Store Builder Library.

Methods perform actions directly through JavaScript instead of HTML. This provides additional flexibility in your code.

With Methods, you can perform many Actions, including: Add, Checkout, Promo, Reset, and ViewCart. However, instead of data-fsc-action, Methods use fastspring.builder.

Each method requires 2 parts:

  • The Store Builder Library script
  • The JavaScript method

Callback Functions

All public methods in the Store Builder Library accept a callback function. This allows you to wait for the action to complete before running additional code. Callback functions receive the order object as a parameter from the first method. This provides you with more flexibility than the data-data-callback, which is only called one time for a request chain.

❗️

fastspring.builder.checkout() does not accept a callback due to its finite nature.

In the example below, the callback function adds the product to the cart. Then, it retrieves data and updates the text to say “Example Product was added to the cart.”

fastspring.builder.add("example-product", function(data){
	    console.log( "example-product was added to cart", data);
    });

Methods

Add Product

The fastspring.builder.add(product) method adds a product to the cart by changing the selected attribute from False to True. This does not adjust the quantity of the product.

fastspring.builder.add('example-product');

Checkout

The fastspring.builder.checkout() method initiates the Popup checkout. You can pass a Session ID or parameter to launch the session within the Popup Storefront, or to direct customers to a Web Storefront. This method does not accept callbacks.

fastspring.builder.checkout();

Clean

The fastspring.builder.clean() method resets the cart after a consumer completes their purchase. No input is required.

fastspring.builder.clean();
fastspring.builder.add('example-product');

Country

Add a country code to fastspring.builder.country(countryCode) to change the country associated with the order. This localizes the page and changes the pricing to include the appropriate currency and tax. The country code format is ISO 3166-1 alpha-2

fastspring.builder.country('de'); //Switch to Germany

Language

Add a language code to fastspring.builder.language(languageCode) to change the language associated with the order. This may affect price and localization formatting in your store. The language code format is ISO 639-1.

fastspring.builder.language('DE'); //Switch to German

Payment

The fastspring.builder.payment(“paypal”) method sets PayPal as the customer's payment method. Then, it redirects to Paypal for the buyer to approve the purchase.

fastspring.builder.payment('paypal');

Postal Code

The fastspring.builder.postalCode() method collects the postal code of each US-based transaction. FastSpring uses this to calculate the sales tax. This allows you to display sales tax amounts for US orders on your page prior to checkout.

fastspring.builder.postalCode(“12345”)

Promo Code

Add a coupon code to fastspring.builder.promo(code) to apply the coupon to an order session. When FastSpring validates the code, the pricing information automatically changes to reflect the discount.

fastspring.builder.promo(“EXAMPLECOUPON”)

Push

The fastspring.builder.push(object) method pushes all order session information to FastSpring with a JSON object. See Session Object to pass a session object to the SBL using this method.

In the example below, a variable resets the cart, adds 3 example products, collects the contact information and language, and pushes it to FastSpring.

var mySession = {
  "reset": true,
  "products" : [
    {
      "path":"example-product",
      "quantity": 3
    }
  ],
  "paymentContact": {
    "email":"[email protected]",
    "firstName":"John",
    "lastName":"Doe"
  },
  "language":"en"
};
fastspring.builder.push(mySession);

Recognize Secure Payload

The fastspring.builder.recognize(securePayload, secureKey) method prefills unauthenticated customer information to the browser session. This does not hide the input fields during checkout; the information is not visible to customers in the response builder object.

fastspring.builder.recognize(
	{
		"email":"[email protected]",
		"firstName":"myFirstName",
		"lastName":"myLastName"
	}
);

Recognize Recipients

The fastspring.builder.recognizeRecipients({recipient object}) method prefills unauthenticated gift recipient information to the browser session. This does not hide the input fields during checkout.

This information is not visible as plain text in the response builder object; it must be accessed through the session.

fastspring.builder.recognizeRecipients(
	{
		"email":"[email protected]",
		"firstName":"myFirstName",
		"lastName":"myLastName",
		"address": {
			"addressLine1": "Address Line 1",
			"city": "City",
			"region": "California",
			"postalCode": "93101",
			"country": "US"
		},
		"memo": "Happy Birthday!"
	}
);

Remove a Product

The fastspring.builder.remove(product) method removes a specific product from the cart. This changes the 'selected' attribute to false and resets the quantity to 1. No other product is affected.

fastspring.builder.remove('example-product');

Reset the Cart

The fastspring.builder.reset() method empties the customer's cart. If you do not pass a session object, you can call this method on page load to ensure the cart information is up to date.

fastspring.builder.reset();

Secure Payload

The fastspring.builder.secure(securePayload, secureKey) method passes sensitive data over a secure request. Sensitive data may include contact, payment, or pricing information.

If the contact information is specified in a JSON object, it will be hidden from the checkout page. If you use the JSON object in a live storefront, encrypt it on the server side beforehand. You can use the method in test mode without encryption. For more information, see Pass a Secure Request.

fastspring.builder.secure(
	{
		"contact": {
			"email":"[email protected]",
			"firstName":"John",
			"lastName":"Doe"
		},
		"items": 
		[
			{
				"product": "example-product",
				"quantity": 1,
				"pricing": {
					"price": {
					"USD": 19.00
					}
				}
			}
		]
	}
);

Tags

The fastspring.builder.tag({‘key1′:’value1’, ‘key2’:’value2’… }) method attaches order-level tags as key-value pairs to orders. The SBL takes one or more key-value pairs as input; then it applies tag(s) to the session. Use JSON formatting to supply the key-value pairs. The maximum number of characters is 4,000.

fastspring.builder.tag({'myKey':'myValue'});

Tax ID

Pass a customer's VAT ID through fastspring.builder.taxId(vatExclusionCode) to remove the tax from the order. FastSpring will validate the ID with the customer’s country. If valid, FastSpring will apply their VAT ID to the order and remove tax.

fastspring.builder.taxId(“XY999999999”document.getElementById('taxId0').value);

Update Product Quantity

The fastspring.builder.update(string product, int quantity) method updates the product quantity in the cart using associated product parameters and an integer.

fastspring.builder.update('example-product', 5);

View Cart

The fastspring.builder.viewCart() opens the Popup Storefront cart page; this method does not expect input.

fastspring.builder.viewCart();