Just launched
We're actively working on new content and improvements to our documentation. We'd love to hear your thoughts, launch quick survey
Paddle Billing

Build a pricing page

Get a step-by-step overview of how to build a pricing page that displays localized prices, including taxes and discount calculation. Pass prices to Paddle.js when a prospect wants to subscribe.

Pricing pages show prospects the subscription plans, addons, or one-time charges that you sell and how much they cost. They're one of the most important pages on your website, and typically play a key part in customer conversion.

You can use the Paddle API and Paddle.js to build pricing pages that show prospects prices that are relevant for their country, displayed in their local currency with estimated taxes. If you're running a sale or promo, you can calculate discounts too.

How it works

Paddle Checkout automatically shows the correct prices for a customer using geolocation to estimate where a customer is buying from. Customers see prices in their local currency, with taxes estimated for their country or region.

You can use the Paddle API to get localized prices for pricing pages or other pages on your website. This means you can show the same information on your pricing page that a customer sees when they open checkout to subscribe.

You don't need to do any calculations yourself or manipulate returned data. Paddle returns totals formatted for the country or region you're working with, including the currency symbol.

Address information

Including address information means Paddle can estimate taxes and localized pricing in the response. When working with pricing pages, you might not have captured address information yet. In this case, you can send:

  • customer_ip_address

    Paddle fetches location using the IP address to estimate tax and localized pricing.

  • address object, containing country_code and (optionally) postal_code

    Paddle uses the supplied country and ZIP code (where included) to estimate tax and localized pricing.

  • customer_id, address_id, and business_id

    Paddle uses existing customer entities to estimate tax and localized pricing. Typically used for logged-in customers who may be considering other subscriptions.

Before you begin

You'll need to create a product and a related price for the items that you'd like to include on your pricing page.

To handle signup from a pricing page, you'll need to build a checkout or page that includes Paddle.js that you can pass a list of items to.

Get a step-by-step overview of how to build a complete checkout — including passing checkout settings. See: Build an overlay checkout or build an inline checkout

Get started

To build a pricing page:

Send a request to the pricing preview endpoint

To preview prices, include a list of items items, with an object containing price ID and quantity for each in your request.

Unlike when working with transactions or subscriptions, you can send items with different billing periods.

You can also include:

  • Customer and address information
  • Discount
  • Currency code

When you include address information, Paddle returns tax calculations and localized pricing.

To avoid exposing your API key and other sensitive data, do not make requests to the Paddle API directly from your frontend. Build functionality into your backend to handle requests and serve just the information you need to your frontend.

Entities in the API have an Access-Control-Allow-Origin header to block access from browsers.

Send a POST request to the /pricing-preview endpoint.


Update your page based on the response

Update information on your pricing page based on the response from the pricing preview endpoint.

Common fields from the response that you may need:

details.address.country_codeCountry code for the pricing preview. If you sent an IP address, Paddle returns the detected country.
details.currency_codeCurrency code for this pricing preview. You may also include currency_code in your request to set manually.
details.line_items[].formatted_totalsTotals for a particular line item, formatted as a string for the currency you're working with.
details.line_items[].formatted_unit_totalsTotals for one unit of a particular line item, formatted as a string for the currency you're working with.
details.line_items[].discounts[].formatted_totalTotals amount discounted for a discount applied to a line item, formatted as a string for the currency you're working with.

Your pricing page may let prospects manually choose their country or currency, or adjust quantities using a seat slider or similar functionality. In this case, make an updated request to the pricing preview endpoint with the new country, currency, or items and update your page based on the response.

Open a checkout for signup

Pricing pages typically include a "Subscribe" or "Buy now" button that lets prospects sign up for a plan or a make a purchase.

To open a checkout to handle sign up from a pricing page, extract items and address data from your pricing preview request, then pass them to Paddle.js to open a checkout.

Common fields in a pricing preview request and how they map to properties for Paddle.Checkout.open() or as HTML data attributes:

Pricing previewJavaScript propertyHTML data attribute

See: Pass or update checkout items

Related pages