Prices
Configure prices per currency and region, define amounts, and link prices to products to reuse them across subscriptions and invoices
Prices determine the cost of products across currencies and locations. You can assign different currencies to product prices in specific regions, simplifying purchases for customers who prefer their local currency.
Multi-currency pricing
Billing 2.0 uses explicit price selection. To charge a customer in a specific currency or apply regional pricing, create a separate price for that currency and pass its product_price_id in the subscription line items.
In Billing 1.0, for multi-currency products, include geo_country and currency parameters with product_id in your payment requests. When these parameters are missing, the system charges customers with the product default currency instead.
For example, customers purchasing a product sold in Poland might be charged in EUR as the default currency instead of PLN. This happens when you do not specify the local currency.
Always verify that the currency and geo_country parameters match the customer’s location and expected payment currency.
The default price of a product may differ from the price set for specific product currencies. Customers in different countries might be charged varying amounts due to currency conversion rates and regional pricing strategies.
For example, you set a default price and add country-specific prices to support tailored pricing in Europe. These additional prices may differ in amount, currency, and location.
If a payment request includes currency EUR and geo_country FRA, the customer is charged the France-specific price in euros.
When reviewing your pricing strategy, check not only the default price but also the country-specific prices.
Trial pricing
In Billing 2.0, trial pricing is configured at the subscription level. You set the trial amount and currency directly when creating a subscription.
In Billing 1.0, you set the trial price at the price level. You can set the trial price to the desired amount in the smallest currency unit. For example, to offer a recurring product for under $1 during the trial period, set the price to $0.99 or any other preferred amount.
Not all
Create price
Create priceAPI v1 endpoint allows you to create a new product price. Provide the necessary details such as the product ID, merchant information, default price, status, product price, trial price, currency, and country.
Once you add the price, you get a response containing the price identifier, creation, and update timestamps, default status, price values, currency, and country. In case of any issue, the response contains the corresponding error code.
To create a price with a new currency
- Go to Billing > Products.
- Find the product you need and click on it.
On the product details page, click on + Add price️ and specify:
- Currency
- Amount
- Location
- Click on Save changes to confirm.
Once added, the new currency is displayed in the Currencies and locations list. Within this list, you can modify or remove added currencies.
Edit price
Edit a price to update its amount, currency, country, or status.
What you can edit depends on whether that specific price has subscriptions. If none exist, or all subscriptions have expired, the price is fully editable. Otherwise, the amount, currency, and country are locked from editing for that price. Trial price is a separate, product-level trial setting, and it is tied to the default price. Promoting a price to default using the default field is an exception. It is allowed regardless of subscription status, as long as product_price, trial_price, or currency are not changed in the same request.
To change the default price when it has active subscriptions, create a new price with the updated amount, promote it to default, then archive the old default price.
Update priceAPI v1 endpoint updates an existing product price. Provide the product ID, product price ID, and the fields to update, such as status, product_price, trial_price, currency, country, and default.
Each price has one of three status values: active, disabled, or archived. You can set a price to active or disabled directly. Archiving is the only way to move a price to the archived status.
In addition to status changes, you can promote a different price to become the product’s default by setting default to true. The following conditions apply:
- Only an active price without a
countryvalue can become default. defaultcannot be combined withcountryor adisabledstatus in the same request.- If the price has associated subscriptions,
defaultcannot be combined withproduct_price,trial_price, orcurrencyin the same request. - Promoting a price to default on its own is always allowed.
Setting default to false on the current default price returns a validation error. Promote a different price to default instead. The previous default price stays active after a new price is promoted. It is not archived automatically.
To edit the product price
- Go to Billing > Products.
- Find the product and click on it.
- In the Product section, click on Edit.
- Find the Default price and change the amount.
- Click on Save changes to confirm.
If you change product details after the initial subscription setup, the customer might be charged based on the updated product details. To verify this, check the Audit log in Account settings. Find the Edit product event and compare the purchase date with the product update date.
Logs in the Hub are available for one year. If you need older data, contact us for assistance.
Archive price
Archive an alternative price when you no longer want to offer it for new subscriptions or when you need to replace it with a new price:
- Remove the price from use for new subscriptions without affecting existing customers.
- Replace the price by creating a new price for the same currency and country with the updated amount, then archive the old price.
You cannot archive the default price. Promote a different active price to default first, then archive the former default price separately.
Archive priceAPI v1 endpoint archives a price. Provide the product ID and product price ID.
To archive a price
- Go to Billing > Products.
- Find the product and click on it.
- In the Currencies and locations list, find the price you want to archive.
- Click on Archive and confirm.
New subscriptions use the new price, while existing subscriptions continue billing at the archived price regardless of subscription status.
- Archiving is permanent. You cannot restore an archived price.
- You cannot archive a product’s default price or a price that is already archived. To archive the current default price, first promote a different price to default.
- If you archive the last active price for a currency, the product cannot accept new subscriptions in that currency until you add a replacement price.
Retrieve price details
Get product priceAPI v1 endpoint retrieves product prices based on filters such as currency, country, and trial availability. Provide the product ID and pagination settings to control the results.
Retrieve pricesAPI v1 endpoint retrieves prices in bulk based on filter criteria. By using filters such as updated_at and default, you can access up-to-date price data. Use it to manage price updates and keep your inventory in sync.
Pagination parameters allow you to control the number of items returned, reducing the API load and preventing rate limit violations during database synchronization.
Upon a successful request, the API responds with a JSON object containing an array of product data and pagination information.