gplay-ppp-pricing

What this skill does

# PPP Pricing (Per-Region Pricing)

Use this skill to set different prices for different countries based on purchasing power parity or custom pricing strategies.

## Preconditions
- Ensure credentials are set (`gplay auth login --service-account` or `GPLAY_SERVICE_ACCOUNT` env var).
- Use `GPLAY_PACKAGE` or pass `--package` explicitly.
- Know your base region (usually US) and base price.

## Critical: Required flags

When updating subscriptions or one-time products that modify pricing, you **must** provide:

- **`--regions-version`**: Required by the Google Play API when updating regional pricing. Use the **latest** version. If you don't know the current version, send any value (e.g., `"2022/02"`) — the API error will tell you the latest (e.g., `latest value is ExternalRegionLaunchVersionId{versionId=2025/03}`). Then retry with the correct version.
- **`--update-mask "basePlans"`**: Required for subscription updates. Without it, the API returns: "update_mask must contain at least one path."
- For one-time products, use `--update-mask "purchaseOptions"`.

## Critical: Preserve all existing regions (fetch-then-merge)

**The Google Play API rejects updates that remove existing regional configs.** If a subscription already has 173 regions configured and you send only 30 PPP regions, the API returns: "Regional configs were removed from the base plan: BM, BO, CI..."

**Always follow the fetch-then-merge pattern:**
1. Fetch the current product to get ALL existing regional configs
2. Override only the PPP target regions with your calculated prices
3. Send the complete merged list (all original regions + PPP overrides)

This also applies to:
- **`otherRegionsConfig`** for subscriptions — if it was previously set on a base plan, it **must** be included in the update JSON.
- **`newRegionsConfig`** for one-time product purchase options — if it was previously set (with `usdPrice`, `eurPrice`, and `availability`), it **must** be included. Omitting it causes: "Cannot remove currency for new regions once it has been added: EUR."

## Critical: Currency codes come from Google Play, not from assumptions

**Do NOT hardcode currency-to-region mappings.** Currency codes vary depending on the `--regions-version` value (e.g., Bulgaria BG uses BGN in older versions but EUR in newer versions after eurozone adoption).

**Always use the currency codes from the fetched existing regional configs.** For PPP target regions where you override the price, use the currency from the multiplier table below. For all other regions, preserve the existing currency exactly as returned by Google Play.

## PPP Multiplier Table

Apply these multipliers to the base USD price. Round all results to `.99` endings (e.g., $4.73 → $4.99, ₹249.37 → ₹249.99).

### Tier 1 — Full Price (1.0x–1.1x)
| Region | Code | Multiplier | Currency |
|--------|------|-----------|----------|
| United States | US | 1.0x | USD |
| United Kingdom | GB | 1.0x | GBP |
| Germany | DE | 1.0x | EUR |
| Australia | AU | 1.0x | AUD |
| Switzerland | CH | 1.1x | CHF |
| Canada | CA | 1.0x | CAD |
| Netherlands | NL | 1.0x | EUR |
| Sweden | SE | 1.0x | SEK |
| Norway | NO | 1.05x | NOK |
| Denmark | DK | 1.0x | DKK |

### Tier 2 — Medium (0.6x–0.8x)
| Region | Code | Multiplier | Currency |
|--------|------|-----------|----------|
| France | FR | 0.8x | EUR |
| Spain | ES | 0.7x | EUR |
| Italy | IT | 0.7x | EUR |
| Japan | JP | 0.8x | JPY |
| South Korea | KR | 0.7x | KRW |
| Poland | PL | 0.6x | PLN |
| Portugal | PT | 0.7x | EUR |
| Czech Republic | CZ | 0.6x | CZK |
| Greece | GR | 0.65x | EUR |
| Chile | CL | 0.6x | CLP |
| Saudi Arabia | SA | 0.8x | SAR |
| UAE | AE | 0.8x | AED |

### Tier 3 — Low (0.3x–0.5x)
| Region | Code | Multiplier | Currency |
|--------|------|-----------|----------|
| India | IN | 0.3x | INR |
| Brazil | BR | 0.5x | BRL |
| Mexico | MX | 0.45x | MXN |
| Indonesia | ID | 0.3x | IDR |
| Turkey | TR | 0.35x | TRY |
| Vietnam | VN | 0.3x | VND |
| Philippines | PH | 0.35x | PHP |
| Egypt | EG | 0.3x | EGP |
| Colombia | CO | 0.4x | COP |
| Argentina | AR | 0.3x | ARS |
| Nigeria | NG | 0.3x | NGN |
| Pakistan | PK | 0.25x | PKR |
| Thailand | TH | 0.4x | THB |
| Malaysia | MY | 0.45x | MYR |
| South Africa | ZA | 0.4x | ZAR |
| Ukraine | UA | 0.3x | UAH |

## Workflow: Set PPP-Based IAP Pricing (legacy `inappproducts` API)

Use this workflow for legacy managed products created via `gplay iap`. These use the `priceMicros`/`currency` format.

### 1. List in-app products
```bash
gplay iap list --package "PACKAGE"
```

### 2. Get current product details
```bash
gplay iap get --package "PACKAGE" --sku "SKU"
```
Note the current `defaultPrice` as your base price, and **save all existing `prices` entries**.

### 3. Build PPP-adjusted prices JSON (fetch-then-merge)

**You must include ALL existing region prices, not just PPP targets.** Fetch the current product, then override PPP regions.

```json
{
  "sku": "premium_upgrade",
  "defaultPrice": {
    "priceMicros": "9990000",
    "currency": "USD"
  },
  "prices": {
    "US": { "priceMicros": "9990000", "currency": "USD" },
    "IN": { "priceMicros": "2499900", "currency": "INR" },
    "BR": { "priceMicros": "24990000", "currency": "BRL" },
    "GB": { "priceMicros": "9990000", "currency": "GBP" },
    "DE": { "priceMicros": "9990000", "currency": "EUR" }
  }
}
```

### 4. Update the product
```bash
gplay iap update \
  --package "PACKAGE" \
  --sku "SKU" \
  --json @ppp-prices.json
```

### 5. Verify prices
```bash
gplay iap get --package "PACKAGE" --sku "SKU"
```

## Workflow: Create New One-Time Product with PPP Pricing

Use this workflow when creating a **brand new** one-time product with PPP pricing from scratch.

### 1. Reference an existing product for regional config structure
If you have an existing OTP, fetch it to use as a template for the regional config format:
```bash
gplay onetimeproducts get --package "PACKAGE" --product-id "EXISTING_PRODUCT_ID"
```
Note the `regionsVersion` and the structure of `regionalPricingAndAvailabilityConfigs`.

### 2. Build the product JSON with PPP pricing

Build the full product JSON including listings, purchase options, and all regional pricing configs. Price format uses `units`/`nanos`/`currencyCode` (see format reference below).

```json
{
  "productId": "premium_lifetime_50off",
  "listings": [
    { "languageCode": "en-US", "title": "Premium (50% off)", "description": "Lifetime access at 50% off" }
  ],
  "purchaseOptions": [
    {
      "buyOption": { "legacyCompatible": true },
      "newRegionsConfig": {
        "availability": "AVAILABLE",
        "usdPrice": { "currencyCode": "USD", "units": "14", "nanos": 990000000 },
        "eurPrice": { "currencyCode": "EUR", "units": "13", "nanos": 990000000 }
      },
      "regionalPricingAndAvailabilityConfigs": [
        { "regionCode": "US", "availability": "AVAILABLE", "price": { "currencyCode": "USD", "units": "14", "nanos": 990000000 } },
        { "regionCode": "IN", "availability": "AVAILABLE", "price": { "currencyCode": "INR", "units": "373", "nanos": 990000000 } },
        { "regionCode": "BR", "availability": "AVAILABLE", "price": { "currencyCode": "BRL", "units": "37", "nanos": 990000000 } }
      ]
    }
  ]
}
```

### 3. Create the product

**`--regions-version` is required even for creation** — the `create` command uses PATCH with `allowMissing=true` internally:
```bash
gplay onetimeproducts create \
  --package "PACKAGE" \
  --product-id "premium_lifetime_50off" \
  --json @new-otp.json \
  --regions-version "2025/03"
```

The product is created in **DRAFT** state.

### 4. Activate the purchase option

New products start in DRAFT. Use `purchase-options batch-update-states` to activate:
```bash
gplay purchase-options batch-update-states \
  --package "PACKAGE" \
  --product-id "premium_lifetime_50off" \
  --json '{"requests":[{"activatePurchaseOptionRequest":{"packageName":"PACKAGE","productId":"premium_lifetime_50off","purchaseOptionId":"default"}}