# 🌍 Parity Pricing API **Fair prices for every country — powered by real World Bank PPP data.** Set your base price once. Get purchasing-power-adjusted prices for 150+ countries instantly.

--- ## What it does You tell us your product's price (say **$49.99 USD**), and we give you the fair price for any country — adjusted using **Purchasing Power Parity** data from the World Bank. > A customer in India shouldn't pay the same dollar amount as one in the US. > Their local buying power is different. This API fixes that. - 🌐 **150+ countries** with local currency prices - 💰 **PPP-adjusted** where data exists, exchange-rate fallback for the rest - ✨ **Charm-priced** automatically ($49 instead of $47.32) - 📈 **Drift detection** to know when your prices need refreshing - 🔄 **Daily exchange rate updates** — always current data --- ## Quick Start ### 1. Create a product ``` POST /init Content-Type: application/json { "name": "Pro Plan", "currency": "USD", "amount": 49.99 } ``` **Response** `202`: ```json { "productId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } ``` ### 2. Get a country's price ``` GET /get?productId=YOUR_ID&countryCode=IN ``` **Response** `200`: ```json { "productId": "a1b2c3d4-...", "countryCode": "IN", "currency": "INR", "amount": 999, "baseCurrency": "USD", "baseEquivalent": 11.86 } ``` > `baseEquivalent` is the local-currency `amount` converted back to the product's base currency using current exchange rates — handy for accounting and revenue reconciliation. That's it. Two calls to go global. 🎉 --- ## Endpoints ### `POST /init` — Create a product Registers a product and calculates prices for all countries in the background. | Body Field | Type | Required | Example | |------------|------|----------|---------| | `name` | string | ✅ | `"Pro Plan"` | | `currency` | string | ✅ | `"USD"` | | `amount` | number | ✅ | `49.99` | **Returns**: `202` with `{ "productId": "..." }` > ⚠️ Prices populate in the background. If you call `/get` immediately, you may get a `503`. Wait ~5 seconds and retry. --- ### `GET /get` — Get a country's price Returns the frozen, PPP-adjusted price for a single country. | Query Param | Type | Required | Example | |-------------|------|----------|---------| | `productId` | string | ✅ | `"a1b2c3d4-..."` | | `countryCode` | string | ✅ | `"IN"` | | Status | Meaning | |--------|---------| | `200` | Price found | | `400` | Missing params | | `404` | Product or country not found | | `503` | Prices still loading — retry in 5s | --- ### `GET /reset` — Refresh prices Recalculates all prices using the latest PPP + exchange rate data. **This is the only way to update prices after initialization.** | Query Param | Type | Required | Description | |-------------|------|----------|-------------| | `productId` | string | ✅ | Product ID | | `currency` | string | ❌ | New base currency | | `amount` | number | ❌ | New base price | **Returns**: `200` with `{ "success": true }` --- ### `GET /status` — Check price drift Compares your frozen prices against what they'd be with today's data. Read-only — changes nothing. | Query Param | Type | Required | |-------------|------|----------| | `productId` | string | ✅ | **Response**: ```json { "productId": "...", "drift": 0.032, "interpretation": "Prices are well-aligned with current data." } ``` | Drift | Meaning | |-------|---------| | `< 0.05` | ✅ Prices are accurate | | `0.05 – 0.15` | ⚡ Moderate drift — consider `/reset` | | `> 0.15` | 🚨 Significant drift — call `/reset` | --- ## Important Notes ### Prices are frozen after creation `/init` calculates and **locks** all prices. They never change automatically. Daily exchange rate updates only affect *new* products and `/reset` calls. Your existing prices stay stable until you explicitly call `/reset`. ### Prices take ~5 seconds after `/init` The background calculation needs a moment. If `/get` returns `503`, just wait and retry. Check the `Retry-After` header. ### Use country codes, not currency codes `/get` expects **country codes** like `IN`, `US`, `BR` (ISO 3166-1 alpha-2), not currency codes like `INR`, `USD`, `BRL`. ### Currency codes are ISO 4217 For `/init`, use standard codes: `USD`, `EUR`, `GBP`, `INR`, `JPY`, etc. ### Charm pricing is automatic All prices come back charm-priced: | Raw | Charmed | |-----|---------| | $7.42 | $7.99 | | $43.17 | $49 | | $4,721 | $4,999 | ### Two pricing methods - **PPP-adjusted** (preferred) — for countries with World Bank PPP data (~130 countries) - **Exchange rate converted** — for the rest, using daily-updated market rates ---