Pass and Capture Custom Order Tags and Product Attributes
Overview
How to pass and capture custom order-level tags and product-level custom attributes for each transaction.
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).
Tags
Tags let you pass arbitrary JavaScript objects, simple arrays, and other parameters to an order. You apply tags to the "order object" (e.g., when integrating with Store Builder Library). Tags are returned 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 customer places an order
- 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 you can obtain them via webhooks and the /orders endpoint.
You can pass tags using any of these methods:
| Method | Sub-method | More Information |
|---|---|---|
| Store Builder Library | Using the "tags" field in the session object | Accessing Library from JavaScript |
| Store Builder Library | Using the fastspring.builder.tag(key,value) method | Accessing Library from JavaScript |
| Store Builder Library | Using a secure payload | Passing Sensitive Data with Secure Requests |
| FastSpring API | Passed to /sessions or /orders endpoints in the corresponding scopes | FastSpring API /orders /sessions |
| FastSpring API | Added to or updated on an existing order record | /orders |
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. Attributes are 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 does 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 } } ] }