Global Pricing Recommendations — localize subscription prices

Global Pricing Recommendations API

What it does

Global Pricing Recommendations helps you generate market-specific subscription prices from a single home-market price. Send a basePrice, baseCurrency, and homeCountry, and you get back a list of recommended prices for international markets.

Each recommendation includes the target countryCode, countryName, a recommendedPrice formatted in the local currency, and a justification explaining how the figure was derived. The request can also include billingFrequency (monthly, weekly, or annually) and an annualDiscountPercent for annual plans.

Use Global Pricing Recommendations when you need to localize pricing for different countries without maintaining separate pricing logic in your app. It is useful for subscription products, regional launch planning, and pricing experiments where you want a consistent method for translating a base price into local market recommendations.

The response is structured for easy downstream use in dashboards, internal tools, or pricing workflows that need to compare countries and present the rationale alongside each suggested price.

Quickstart

Generate pricing recommendations for a subscription using your base price, currency, and home country.

curl -X POST "http://localhost:8080/namastesumalya/generate-global-pricing-recommendations" \
  -H "apy-token: $APY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "basePrice": 29.99,
    "baseCurrency": "USD",
    "homeCountry": "USA"
  }'

What you'll get back

Returns a JSON object with a recommendations array. Each item in the array is an object with countryCode, countryName, justification, and recommendedPrice fields.

{
  "recommendations": [
    {
      "countryCode": "IND",
      "countryName": "India",
      "justification": "Adjusted from your base price using Purchasing Power Parity (PPP), local wage data, and currency conversion for a monthly billing cycle.",
      "recommendedPrice": "₹499"
    }
  ]
}

About this endpoint

What it does

Generates pricing recommendations for multiple international markets based on a base subscription price, base currency, and home country. The response returns a list of country-level recommendations with the recommended price, country name, country code, and justification.

Request Body

Parameter	Type	Mandatory	Description
basePrice	Number	Yes	Base subscription price in the home market.
homeCountry	String	Yes	ISO 3166-1 alpha-3 three-letter country code representing the home market (e.g., USA, IND, GBR).
baseCurrency	String	Yes	ISO 4217 currency code for the base price (e.g., USD, EUR, INR).
billingFrequency	ENUM	No	Billing cycle for the subscription. Allowed values: `monthly`, `weekly`, `annually`. Defaults to `monthly` if not provided.
annualDiscountPercent	Number	No	Discount percentage applied for annual billing plans. Must be between 0 and 100.

Response

Returns a JSON object with a recommendations array field. Each item in recommendations is an object with countryCode, countryName, justification, and recommendedPrice fields.

Parameter	Type	Mandatory	Description
recommendations	Object Array	No	List of pricing recommendations, one per country.
recommendations[].countryCode	String	No	ISO 3166-1 alpha-2 two-letter country code.
recommendations[].countryName	String	No	Full name of the country.
recommendations[].justification	String	No	Explanation of how the recommended price was derived for this market.
recommendations[].recommendedPrice	String	No	Recommended price formatted with the local currency symbol and amount.

Body

Name

Type

Description

bodyREQUIRED

object

Request body for generating global pricing recommendations.

Quickstart

What you'll get back

About this endpoint

What it does

Request Body

Response

Body

Errors any endpoint can return