Using Optional Parameters

Sometimes you may want customers to see a specific state or version of your store. One common way to accomplish this is to embed a URL parameter, which is a variable on the end of the URL link to your order pages. Most of the following parameters require additional setup within SpringBoard before using. You can also use add optional parameters to your order page URLs to pre-fill customer information which you've already collected on your website.

Adding Optional Parameters to your Order Page URLs

The first parameter is passed by appending a question mark ?, then the name of the parameter, and then the value for the parameter to the original URL. In this example, the company ID is julie and the product's Partial URL Path Name is fontmaker, and the original URL would be:

http://sites.fastspring.com/julie/product/fontmaker

If you wanted to have a coupon named HALFOFF automatically filled in during the order process, the URL would be:

http://sites.fastspring.com/julie/product/fontmaker?coupon=halfoff

To add more than one parameter to the URL, after the first parameter ?coupon=halfoff, use an ampersand & to separate the parameters from each other. In this example, in addition to automatically filling in the coupon code, it would make the gift option appear.

http://sites.fastspring.com/james/product/digitalproduct?coupon=halfoff&option=gift

To add a third parameter, add another ampersand & , then the name of the parameter, and then the value for the parameter.

http://sites.fastspring.com/james/product/digitalproduct?coupon=halfoff&option=gift&referrer=education

Testing Optional Parameters

To test any of the optional parameters listed below, go to SpringBoard's Store Home » Store Testing and click on the Optional Parameters tab. Then enter in a value for the parameter. Click on the Testing Links tab and, based on the page linking option you will use to connect your website to your FastSpring store, you should select the appropriate testing link from the choices: Detail, Cart, or Short. Some of the page linking options require minor tweaks in Store Testing, as described in Store Testing within SpringBoard.

Optional Parameters

The optional parameters are described below. When applicable, we have also provided support articles that detail the setup process required for the optional parameter to make your FastSpring store appear or operate differently to a customer.

Coupon (coupon=...)

This parameter would apply a coupon code to an order without requiring the customer to enter the code during the checkout process. Some of our clients choose to hide the coupon field in the order process and only pass the coupon codes this way.

Tags (tags=...)

This parameter has many uses within SpringBoard. A tag is a variable that can hold any positive integer value. If no value is specified, it holds a value of 1. Tags can be used by parts of the order process. For example, they are commonly used in a custom price calculation written in JavaScript and in the logic of an Email Fulfillment. Tags can be passed to a license generator, returned in a Notification, or used as a condition for an offer, price, style, etc. Tags set this way are considered to be part of the environment, while tags set directly on products are attached to the quantity of that product. Adding multiple tag parameters can be achieved by separating each tag (sometimes with numeric value) with a comma, as shown below.

?tags=mytaga,mytagb,mytagc=2,anothertag=8

Option (option=...)

This parameter gives various options to the order process based on the parameter's value, as described below. These are the only available values for this parameter.

Link Source URL Tag (source=...)

This parameter is used to track link sources. The link sources need to be explicitly defined by going to SpringBoard's Store Home » Link Sources. Sources imply that the link is being sent from a different place than normal, and that the source needs to be tracked or needs to trigger specific differences in the order process. For example, sources can be used as conditions for different styles, prices, or external tracking. Link sources are part of the raw data so you use them in notifications or a custom report. You can track link source usage by going to SpringBoard's Store Home » Reports, and under Promotions, click Sources. Link sources are most commonly used with affiliates to trigger a split pay. We can automatically transfer a portion of a sale into another client's account. Often, these accounts are a special kind of account, called a payee account, which is designed to just receive the money. Note: The source parameter is case sensitive.

Link Source Campaign (campaign=...)

This parameter is a free-form qualifier to be used with a link source. It is simply extra data that be used to accomplish specific things, but is not used with frequency. We suggest you not use this parameter unless we give you instructions to accomplish something that uses it.

Custom Referrer (referrer=...)

This parameter allows you to pass data into an order and then retrieve that data at the end of the order process. For example, you can pass and retrieve a customer's username on your website. A customer's username is useful to have when trying to upgrade a subscription product so that the update gets linked to the username. This referrer data can be also used to generate License Fulfillments and can be included in any type of Notification. You can also use this parameter to require previous license codes to upgrade versions of products. If customers are trying to upgrade through your software application installed on their computer, you can use this parameter to know the customers' current license code and use it to create a new license code.

Custom Catalog (catalog=...)

For the page linking options that have the Continue Shopping button, this parameter specifies the webpage that will appear when clicking that button. This parameter overrides the Continue Shopping Button Behavior settings found by going to SpringBoard's Store Home » Store Settings. Note, this URL must begin with http:// or https://. For example, when using the Shopping Cart - View Product Detail Page page linking option (with Company ID julie and a product Partial URL Path Name of fontmaker), to make the Continue Shopping button go to Yahoo's site, use the URL below.

http://sites.fastspring.com/julie/product/fontmaker?action=adds&catalog=http://www.yahoo.com

Next Period Date (nextPeriodDate=...)

This parameter will pass a date via a URL to define the start of the next subscription period after a free first period (or any part thereof). It will allow you to define the length of a trial period more dynamically. One example where this parameter is used is setting a subscription payment cycle to begin on the first of the month, regardless of when during the prior month the customer signed up. When you link from your website or application to your subscription product in SpringBoard, you can set the end date of the trial period by adding the following to the URL:

?nextPeriodDate=yyyy-mm-dd

For example, adding ?nextPeriodDate=2013-02-20 would set the end date of the trial period to February 20, 2013.

If you set the nextPeriodDate to be the current date or a date in the past, then there will be no trial period and the regular period will begin immediately. The date cannot exceed the length of the trial period configuration. This parameter is restricted to free trial periods and will be ignored in other cases.

Note: The custom date will get cached the first time a customer (or you) reaches your FastSpring store's order page. For testing purposes, you may need to close all browser windows and start with a fresh session to see changes when testing live links.

Class (class=...)

This parameter will set a class on the <body> tag of the order pages. Along with CSS in the style template, this parameter can be used to make changes. One example would be to use this parameter to display a different store logo on your order pages.

Country (country=...) and Language (language=...) and Currency (currency=...)

Using information from our Geo-location service, which detects a customer's IP location, the language, country, and currency is automatically set when a customer places an order. These parameters allow you to force the order process to start as though the customer's location were in a specific country or with a specific language or with a specific currency, by using the two letter language ISO 639-1 code and/or the two letter country ISO 3166-2 code and/or the three letter currency ISO 4217 code (if the currency code is a FastSpring supported currency). You can specify one, two, or all three parameters. For example, if you want to make your order page default to the Spanish language (ISO code: es) and as though the customer's location is in Mexico (ISO code: MX) but have their currency be set to Euros (ISO code: EUR), you can add the following parameters to the URL:

?language=es&country=MX&currency=EUR

Note: The code for country and the code for currency must be capitalized letters.

You can also use these parameters to test your order pages in other languages and countries, or to test a shipping rate that varies by country. When using Store Testing, simply select a Country and/or Language to see how your order pages will appear.

Quantity (?quantity=x)

To pass in a specific quantity of a product, such as 3 units, you can add the following parameter to the URL:

?quantity=3

Mode (mode=...)

This parameter is not listed in store testing's optional parameters. If you want to view live URLs but be able to conduct a test order, you can use this parameter that will display an option for Test Payment. Enter in the same Username and Password that you use to log in to SpringBoard.

?mode=test

Note: Due to caching issues, you may need to close all browser windows and start with a fresh session to see your live URLs in this test mode.

Results in FastSpring Classic Documentation:

Important!