Dynamic Pricing API

1. Introduction

The current document is addressing the details of the Dynamic Pricing API integration with Upclick, as an optional service allowing merchants to send dynamically product information to the Upclick checkout.

2. Checkout Links

In a traditional way an Upclick merchant can generate checkout links for their products within their related merchant accounts offered by the platform. The creation of a checkout link imposes the specifications of few critical elements required at purchase: Product definition and pricing, Checkout Design, Tracking and Configurations.

The Product Definition, accessible under the section “My Products” covers all the products attributes required for promoting the product online (name, description, pricing), as well as the elements required for the product delivery (installer, URL, license keys, etc).

Various combinations of products could be grouped together in a “Pricing Model”, that ultimately will be a component piece of a checkout link. Beside the grouping factor, the pricing model definition allows the merchants to control various behaviours of the cart:

• The order of products displayed
• Overwrite/customize the product name, description and price for the current pricing model (without having to create a new product);
• The product preselection and default quantities;
• The type of display per cart item (not available in all templates);
• The assignment and dependency of cross-sells, post-sales and upsells;
• Force the checkout to eventually ignore products from the pricing model (a list of them or all not sent through the AP parameter);

The Checkout Design and Checkout Content sections are the sections allowing the merchants to control the content and look and feel of the checkout and related pages (terms and conditions, Thank-You page, etc) as well as of the Purchase Confirmation Email.

 

When generating a checkout link for a website, the Pricing Model and Checkout Design are mandatory to be specified.

The checkout link generated will contain a parameter “ujid”, which will uniquely identify your checkout. This parameter will instruct the checkout about all the components defined by merchant in the backend. Direct updates on the related components in the backend will be automatically available in checkouts, under the same checkout link, without changing the checkout identifier.

A sample checkout link is presented below:

https://cm1.Upclick.com/join.aspx?ref=msn.com&ujid=ANhD7vHpX68%3D

Where the ujidis the checkout identifier.

3. Dynamic Pricing

In order to access/code any of the Upclick APIs the merchants has to use the “API Access Code”, generated for each merchant. The code is available in the merchant account interface. Please follow the steps below:

1. Login to Upclick.com;
2. Click on Reporting (located on the top navigation);
3. Click on API's and Tracking;
4. Find the code displayed in the “API access code” section;

 

On top of the default checkout identifier (ujid) sent to the checkout in a regular mode, Upclick supports the parameter “ap”, which is “json” structure that could be used to send extra information to checkout, related with the products promoted through the current checkout (pricing model).

  The syntax for the “ap” parameters is as following:

  {
"TS":"ExpirationTime",
"Products": [
{"ProductUID":"ProductUID","Price":{"Price":{Pricing}},"Name":{ProductName },"Quantity":Quantity},
{"ProductUID":"ProductUID","Price":{"Price":{Pricing}},"Name":{ProductName},"Quantity":Quantity}
],
"ProductIgnore":
{
"Type":"Type",
"List":"comma separated list of UIDs to be ignored"
}
}

Where:

• ExpirationTime - the Unix Time (Epoch Time) of the checkout link expiration; The entire “TS” section is optional. It has to be specified only when an expiration of the link is desired for security or marketing reasons (promotions). Also, if the ExpirationTime is not sent, the entire section “TS” will be ignored.

Example: 1427976389 (ISO 8601:2015-04-02T12:06:29Z)

• ProductUID - the Upclick Product ID from the pricing model related to your checkout that needs to be overwritten. Only Product IDs which are specified in the pricing model are taken in consideration. The Product IDs contained in a Pricing Model are available in the related page in the merchant account interface:

 

A product ID (PID) can start with a “P” (main product) or “C” (cross-sell).


Example: "ProductUID":"P015116"

• Pricing - the product pricing structure specified for all currencies, by using the currency ISO 4217 as follows:

"Price":{"USD":PriceAmount,"GBP":PriceAmount}

Other currencies can be specified, from the currencies supported in the pricing model, separated by comma like in the example below:


Example: "USD":15,"GBP":12,"EUR":10


The pricing model allows merchants to define specific market prices. When the customer comes from countries related to those markets, Upclick checkout will display the merchant defined price for that market. The USD price is always mandatory in the pricing models. If a price is not defined in other currencies, the checkout will use the USD price converted into the local currency by using a daily exchange rate.



Example:

1. "GBP":12

In UK the price displayed will be 12 GBP
In USA the price displayed will be 12 GBP converted to USD
In any other markets/countries the price will be displayed as (12 GBP converted to USD) converted to the local currency


2. "USD":15,"GBP":12

In UK the price displayed will be 12 GBP
In USA the price displayed will be 15 USD
In any other markets/countries the price will be displayed as 15 USD converted to the local currency


3. "USD":15,"GBP":12,"EUR":10

In UK the price displayed will be 12 GBP
In USA the price displayed will be 15 USD
In EU the price displayed will be 10 EUR
In any other markets/countries the price will be displayed as 15 USD converted to the local currency

• ProductName - the product name structure specified for all languages, by using the language ISO 639-1 as follows:

"Name":{"en":"English Product Name","fr":"French Product Name"}

Other languages can be specified, from the languages supported in checkout design, separated by comma like in the example below:


Example: "en":"My product","fr":"Mon produit"

• Quantity - the product quantity, represented as an integer number, which will be displayed in the shopping cart next to the product description.

If the products in the pricing model are recurring they will be processed at the amounts and with the recurring settings configured within the pricing model. Though, with the Dynamic API , there are optional “tags” allowing merchants to also overwrite these ones. A full syntax for an “ap” requests with recurring details is as following:

{
"TS":"ExpirationTime",
"Products": [
{"ProductUID":"ProductUID","Price":{"Price":{Pricing},"RebillDelayValue":RebillDelayValue,"RecurringPrice":{Pricing},"RebillFrequencyValue":RebillFrequencyValue,"RebillNumbers":RebillNumbers},"Name":{ProductName },"Quantity":Quantity},

{"ProductUID":"ProductUID","Price":{"Price":{Pricing},"RebillDelayValue":RebillDelayValue,"RecurringPrice":{Pricing},"RebillFrequencyValue":RebillFrequencyValue,"RebillNumbers":RebillNumbers},"Name":{ProductName},"Quantity":Quantity},
]
}


Where the additional “tags” have the following meaning:

• RebillDelayValue - the time interval between the original transaction and the first rebill, in days;

Example: "RebillDelayValue":7 (first rebill in 7 days)

• RebillFrequencyValue- the time interval between the recurring transactions, in days;

Example: "RebillFrequencyValue":30 (rebilling every 30 days)

• RebillNumbers- the number of rebills; for unlimited use 10000;

Example: "RebillNumbers":5 (rebills 5 times)


A simple sample of an “ap” request as below, will overwrite the USD price of the product P015116 to 15 USD , name to “My Product” and quantity to 2:


{
"TS":"1427976389",
"Products": [
{"ProductUID":"P015116","Price":{"Price":{"USD":15}},"Name":{"en":"My product"},"Quantity":2},
]
}

• ProductIgnore - the structure which will force the checkout to not display some of the products from pricing model (optional)

• Type - the mechanism to ignore products from pricing model supports multiple types (possible values):

1. – the checkout will ignore all products not defined in AP parameter in Products section.
2. – the checkout will ignore all the product from the pricing model for which the UID is provided in the List parameter.

• List -a comma separated list with all the numeric part of the products UIDs which the checkout has to ignore. This parameter is optional (it has to be provided only if type = 2).

Example: "ProductIgnore":{"Type":"2","List":"1566, 3334, 2435"}"

3. – the checkout will ignore all main products not defined in AP parameter in Products section.

Example: "ProductIgnore":{"Type":"3"}"

4. – the checkout will ignore all cross-sells products not defined in AP parameter in Products section.

Example: "ProductIgnore":{"Type":"4"}"

5. – the checkout will ignore all post-sales products not defined in AP parameter in Products section.

Example: "ProductIgnore":{"Type":"5"}"

6. – the checkout will ignore all cross-sells and post-sales products not defined in AP parameter in Products section.

Example: "ProductIgnore":{"Type":"6"}"

Attention, in all cases for ProductIgnore the products sent in the ‘Products” section will not be ignored, even if they are part of the List.

When sending the “ap” parameter value (json) to checkout it has to be first encoded Base64.

In order to secure the “ap” request UpClick requires that merchants are generating a token send separately in the parameter “cverify”.

The parameter value has to be built as the MD5 hash of the following concatenation:


Merchant_API_Access_Code|JSON_string


The validity of the data received is evaluated by the comparison between the ‘cverify’ parameter sent and the one generated by the system. Only if there is an exact match between the two values the checkout will take in consideration the “ap“ parameter.


Example:

Cverify unencoded:

55B7737539399C111344542D|{"Products":[{"ProductUID":"P015137","Price":{"USD":15.99},"Name":{"en":"My Product To Sell"}}]}

Cverify encoded:

e703bf1dbdb4b6c5105352e0e5972d81

4. Testing Dynamic Pricing

Upclick is providing an online tool for developers where “ap” and “cverify” parameters can be generated manually:

https://test.Upclick.com/tools/dynamicprices.aspx

This allows the developers to compare their generated cverify with the one provided by the system. When the cverify is not valid the checkout will simply ignore the dynamic parameters (ap).

 

A final test checkout link with dynamic pricing (20CAD, custom name, Qty=2) looks like the following:

 

Where the original link without dynamic prices looks like:

 

5. Dynamic Pricing Gateway

The page provided above for testing the ‘ap&cverify’ creation acts also as a dynamic gateway that can be used in the checkout flow to dynamically send the parameters and it will return back the ‘ap’ and ‘cverify’. The merchant has to append them to the checkout URL before the client redirect.

The production URL for the Dynamic Pricing Gateway will be provided to each merchant after the integration validation with Upclick. The validation includes also the registration of the IP Address from where the requests are being made.

In order to use this gateway the merchant can send the product information in HTTP GET (Query String) format and if the request is valid Upclick will reply with the ‘ap’ and ‘cverify’ information:

ap=eyJQUiI6bnVsbCwiVFMiOiJcL0RhdGUoLTYyMTM1NTc4ODAwMDAwKVwvIiwiUHJvZHVjdElnbm9y
ZSI6eyJUeXBlIjoyLCJMaXN0IjpbIjE1MTM4IiwiMTU2NzgiLCIyMzQ1Il19LCJQcm9kdWN0cyI6W119&
cverify=0637db46014ea4aa0f650bd4387759d3

This information has to be appended to the checkout URL.

The parameters supported by the Dynamic Pricing Gateway are the following:

• productuid{x}
• price{x}
• name{x}
• rebilldelayvalue{x}
• recurringprice{x}
• rebillfrequencyvalue{x}
• rebillnumbers{x}
• quantity{x}
• productignoretype
• productignorelist

Where:

• {x} – the product index (1...n) starting with 1;


• productuid{x} – the numeric value of Upclick Product UID;(eg. 15138)


• price{x} – the semicolon separated list of “currency column price” (price1=usd:12;cad:15) for product {x} ;


• name{x} – the semicolon separated list of “culture code: product description” (name1=en:”Software A”;fr:” Logiciel A”) for product {x};


• recurringprice {x} – the semicolon separated list of “currencycode:price” (recurringprice 1=usd:12;cad:15) for product {x};


• rebilldelayvalue{x} – the number of days before the first rebill for product {x};


• rebillfrequencyvalue{x} – the number of days between the subsequent rebills for product {x};


• rebillnumbers{x} – the total number of rebills for product {x};


• quantity{x} = the quantity for product {x};


• productignoretype – the parameter which will force the checkout to ignore products :

• productignoretype=1 - ignore all products from the pricing model not defined in AP parameter;


• productignoretype=2 - ignore all products from productignorelist;


• productignoretype=3 - ignore all other main products from the related pricing model;


• productignoretype=4 - ignore all other cross-sell products from the related pricing model;


• productignoretype=5 -ignore all other post-sale products from the related pricing model;


• productignoretype=6 - ignore all other cross-sell and post-sale products from the related pricing model;

Attention: an API request is valid if you provide at least one product in the “products’ section.

The case of productignoretype=2 is the only situation where a product is not required to be sent in the ‘products’ section.

Example:

https://test.upclick.com/tools/dynamicprices.aspx?productignoretype=2&productignorelist=15138,15678,2345

The request above will generate an ‘ap’,’cverify’ pair value, which used in the checkout URL, will have as effect the removal of the products 15138,15678, 2345 from the related pricing model.

Attention, all links provided above as sample, will not be browsable due to the requirement of IP address whitelisting. Only the registered IPs can browse URL related with their accounts.