Set up x-parameters
X-parameters are components of URLs used to pass information through the checkout process, such as:
- Sources of revenue (revenue tracking)
- Customer information
- Affiliate and partner information
- Any other information you'd like to pass
X-parameters are configured for attributes initiated outside the Cleverbridge platform. You can create x-parameters based on an information need that is not inherently included in the Cleverbridge platform, such as a user ID number or the name of a campaign. X-parameters must begin with x-.
An x-parameter for an Easter campaign is x-source=Easter.
Pass x-parameters to Cleverbridge
You can transmit x-parameters to the Cleverbridge platform in several ways:
- Add them to a URL, which can also be done with Link Generator.
- Use JSON.
- Manually add them to a transaction in Purchase Viewer.
There is no limit to how many x-parameters can be added to a transaction.
Add x-parameters to order URLs
After defining x-parameters, you can add them to their corresponding order URLs and start tracking important customer data.
X-parameters must be appended to the Cleverbridge-hosted order URL in order to pass through the order process. As long as the parameter begins with x-, it will be saved in the order process. The number of x-parameters that can be passed is unlimited.
Format
The format of an x-parameter in an order URL is &x-<name>=<value>:
| Parameter | Description |
|---|---|
<name> | Select a name for the additional parameter. All alphanumeric characters are allowed as well as hyphens. This value is case-sensitive. Note that all additional parameters must begin with x-. The first x-parameter appended to the URL must be separated by a question mark (?), after which any additional x-parameters are separated by an ampersand (&). |
<value> | The actual value for the additional parameter you want to pass to the Cleverbridge system. |
&x-tracking=ABC&x-userid=12345
Creating order URLs is a manual process using the following conventions:
- Separate x-parameters from other URL parameters with an ampersand (
&). - If the URL is an MVT URL, (for example,
https://www.shieldwareexamplecompany.com/123/purl-summer2006), the first x-parameter appended to the URL must be separated with a question mark (?), after which any additional x-parameters are separated with an ampersand (&).
The following is an example of a configured order URL that includes an MVT:
https://www.shieldwareexamplecompany.com/123/purl-summer2006?x-source=summercampaign&x-sale=50Add x-parameters to a completed purchase
If you would like x-parameters to be included in revenue reports, you can add them to a completed purchase.
- Navigate to the purchase overview page in our web admin tool.
- Select the General Info tab.
- Scroll to the bottom and click the + sign button next to the X-Parameters field.
- Enter a key/value pair for the x-parameter.
- Click Add.
You can also add x-parameters in Commerce Assistant.
- Go to Transactions > Purchases and double-click the order you would like to add the x-parameter to.
- In the Purchase Details section, click Add Parameter.
- Enter the parameter name (key) and value, and click OK.
If you use this method to add an x-parameter to a subscription-related order, the x-parameter won't be included in future billing events.
Use x-parameters
You can view x-parameters:
- In a specific transaction in Purchase Viewer.
- In reports, for examples, as subscription metrics.
- In the Commerce Assistant:
- In the Purchase Viewer under the Parameters section of Purchase Details.
- In Purchase Search by adding the Parameters column. For details, see Search > Filter search results using grouping filters.
- Within the reports by navigating to Promotions and recommendations > Tracking > Revenue.
Use x-Parameters in notifications
You can use x-parameters in conjunction with notifications for automated transaction and license key generation. This functionality exports data related to the x-parameters to your back-end systems. To learn more about notifications, see Notifications.