Collapse Menu
Docs Home
Extensibility Options
Contact Support

Passing and capturing custom order tags and product attributes

Overview

In some cases, you may want to pass additional information to the order, to be returned once the order has been processed. For those cases FastSpring offers the way to pass "tags" (information on the order level) and "attributes" (information on the product level).

Overview

In some cases, you may want to pass additional information to the order, to be returned once the order has been processed. For those cases FastSpring offers the way to pass "tags" (information on the order level) and "attributes" (information on the product level).

 

In some cases, you may want to pass additional information to the order, to be returned once the order has been processed. For those cases FastSpring offers the way to pass "tags" (information on the order level) and "attributes" (information on the product level).

 Note

For custom order tags, the sum of the number of characters supplied for the Key and the Value must not exceed approximately 4,000 characters.

For product attributes, the sum of the number of characters supplied for the Key and the Value must not exceed approximately 400,000 characters.

Tags

Tags let you pass arbitrary Javascript objects, simple arrays and other parameters to an order. The tags are applied to the "order object" (and can be used when integrating with Store Builder Library), will be passed as part of the Webhooks and appear in all API responses related to the order. For example, you might want to use tags for the following purposes:

  • To pass tracking information and capture it when the order is placed
  • To perform A/B testing to determine the more effective discount or related offer strategies
  • To pass vendor-generated variables such as invoice IDs and more

Tags are not retained in the customer account nor stored for a subscription instance; they are stored as part of the order information and can be obtained via webhooks and /orders endpoint.

Tags can be passed using any of these methods:

MethodSub-methodMore Information
Store Builder LibraryUsing the "tags" field in the session objectAccessing Library from JavaScript
Store Builder LibraryUsing the fastspring.builder.tag(key,value) methodAccessing Library from JavaScript
Store Builder LibraryUsing a secure payloadPassing Sensitive Data with Secure Requests
FastSpring APIPassed to /sessions or /orders endpoints in the corresponding scopes

FastSpring API

/orders

/sessions

FastSpring APIAdded to or updated on an existing order record/orders
 

 Note

If you want to replace the order tags associated with an existing subscription instance, you should update the original order via POST /orders. Posting new order tags or product attributes will replace any existing ones on the order, and future webhook events and API responses about the updated subscription instance will reflect the updated values.

Here is an example of an array that can be set via the session object using Store Builder Library, and returned via webhooks or the response to GET /orders.
var tags = {
    "key": "value",
    "key2": ["value1", "value2", "value3"],
    "key3": 10.55
}
 
fastspring.builder.push({'tags': tags});

 

Attributes

While Tags can be passed and captured on the order level, "attributes" can be passed and captured on the product level. This is useful if you would like to silently pass additional information about the product while preparing the order on your website by using the Store Builder Library or the FastSpring API.  The customer will not see these attributes.

As with tags, product attributes can also be added to or updated on an existing order record via the /orders endpoint of the FastSpring API.

Unlike Tags, when creating a new order via the Store Builder Library, attributes must be passed by using the secure payload. Otherwise, their format is the same.

Here is an example of the items array that must appear on the product level of the secure payload:

{
  "items": [
     {
        "product": "product-one",
        "attributes": {
            "key": "value",
            "key2": ["value1", "value2", "value3"],
            "key3": 10.55
        }
     }
  ]
}

 Note

If you want to replace the product attributes associated with an existing subscription instance, you should update the original order via POST /orders. Posting new order tags or product attributes will replace any existing ones on the order, and future webhook events and API responses about the updated subscription instance will reflect the updated values.

Try FastSpring

Get a free account and see why FastSpring is the ecommerce partner of choice for software providers around the world. Try our full-service ecommerce solution today to unlock revenue growth for your online company.