Localized Prices API

Localized prices on your website.

Displaying Localized Prices

One of the many benefits to using Paddle is its ability to automatically localize your checkout with geo-specific payment options, manage VAT/sales tax calculations and show pricing in the user’s local currency.

This can sometimes result in a disconnect between the prices displayed on your site, and those then immediately displayed on the checkout once opened.

Paddle supports two different methods of displaying local prices on your site, the first is to wrap any amounts in a HTML class, in the example below, the $59 price would be localised:

<p>Grab your copy of My Awesome Product for just <span class="paddle-gross" data-product="12345">$59</span></p>

For example, if you have pricing enabled in Euros (€54) and British Pounds (£45) for the product, users would see the following:

  • A user from the US would see: Grab your copy of My Awesome Product for just US$59!
  • A user from the UK would see: Grab your copy of My Awesome Product for just £45!
  • A user from Germany would see: Grab your copy of My Awesome Product for just €54!
  • etc…

In addition to paddle-gross for the full product price, including VAT, you can also use paddle-tax for the taxable amount of the sale, and paddle-net for the pre-tax price of the product.

If you wish to use the pricing information elsewhere you can pull an object of localized pricing information for the current user for a specified product using the Paddle.Product.Prices(productId, callback) method. Using this method also enables you to retrieve additional data if your product is recurring in nature, including trial periods, localised recurring pricing and billing periods.

Example

<script type="text/javascript">
	Paddle.Product.Prices(12345, function(prices) {
		console.log(prices);
	});
</script>

The Paddle.Product.Prices() method performs an asynchronous call to the Paddle API to pull pricing information. It accepts three arguments, the first productId is the ID of the Paddle Product to pull pricing for, the second quantity is the number of items, and the third callback is a Javascript function to call upon successfully retrieving prices from our API.

The callback will be passed an object of price information in the following format:

{
    "price": {
        "gross": "$9.99",
        "net": "$8.32",
        "tax": "$1.66",
        "tax_included": true
    },
    "quantity": 1,
    "country": "GB"
}

For subscription products, the format of the response is slightly different, an example response to a Paddle.Product.Prices() call for a subscription product is below.

{
    "price": {
        "gross": "$0.00",
        "net": "$0.00",
        "tax": "$0.00",
        "tax_included": true
    },
    "quantity": 1,
    "country": "GB",
    "recurring": {
        "price": {
            "gross": "$1.00",
            "net": "$0.83",
            "tax": "$0.17",
            "tax_included": true
        },
        "subscription": {
            "trial_days": 2,
            "length": 1,
            "type": "month"
        }
    }
}

In the above example for subscriptions, the price object represents our trial period, and the recurring.price object represents our recurring subscription in perpetuity. The recurring.subscription object represents information about the subscription (eg. trial period length, billing interval, billing interval length).

Next Steps

Now your website is localized with multi-currency pricing. What you do next is up to you, but we recommend:
Checkout Parameters
Passing additional parameters allows you to modify the behavior of the Paddle checkout, for example to pre-fill a buyer's email address or set a custom price. Either JavaScript parameters or HTML attributes can be used, depending on your integration.
Order Information
Get information about an order once the transaction completes using Paddle.js
Affiliate Tracking
Automatically track affiliate campaigns and split funds with promotional partners.

Questions about Paddle?

If you need any help regarding your Paddle integration, please get in touch with our Customer Success team using the form below.