Plans

Buy 30 days of a plan from the balance

CHARGES THE BALANCE the tier price for 30 days that never renew (starts now, or queues behind the running period). maxCents caps the charge (409 price_changed). requestId is required: a retry with it returns the same period, never a second charge. Refused while a card plan is active.

POST/v1/account/plan/balanceAPI keySpends balance

Request body

tierstringrequired

Base 499, Pro 1499, Max 3999 cents per 30 days.

Allowed values: basepromax

maxCentsintegerrequired

Most you agree to be charged, in cents.

Allowed range: 0 <= x

requestIdstringrequired

Your idempotency key for this purchase; reuse it on retry, use a new one for a new purchase.

Response

outcomestring

Allowed values: startedqueuedreplayed

startsAtstring

endsAtstring

centsinteger

tiersPlanTier[]

planobject | null

balanceobject

baseTrialobject

usageobject

trialobject

Responses

201Bought (HTTP 201); the body also carries the updated plan status.

400Invalid parameter or body; message names what was expected.

401No valid API key (missing, malformed, unknown or revoked).

402code: insufficient_balance; nothing charged.

409code one of: price_changed (with cents), card_active, fix_payment, checkout_open, already_queued, request_conflict. Nothing charged.

503code: stripe_unavailable or temporarily unavailable; nothing charged.

cURL

curl -X POST -H "x-api-key: $KEY" "https://api.pmwallets.com/v1/account/plan/balance" -H "content-type: application/json" \
  -d '{"tier":"pro","maxCents":1499,"requestId":"b1f0c2e4-7a31-4c55-9c1e-2f6f0a8e51d3"}'

json

{
  "outcome": "started",
  "startsAt": "2026-11-05T10:13:00.000Z",
  "endsAt": "2026-11-05T10:13:00.000Z",
  "cents": 12,
  "tiers": [
    {
      "tier": "base",
      "cents": 12,
      "daily": 12,
      "monthly": 12,
      "push": 12,
      "exports": 12,
      "rank": 12,
      "onSale": true,
      "trialDays": 12
    }
  ],
  "plan": {
    "state": "active",
    "tier": "pro",
    "source": "card",
    "periodStart": "2026-11-05T10:13:00.000Z",
    "periodEnd": "2026-11-05T10:13:00.000Z",
    "endedAt": "2026-11-05T10:13:00.000Z",
    "graceUntil": "2026-11-05T10:13:00.000Z",
    "cancelAtPeriodEnd": true,
    "renewing": true,
    "nextTier": "max",
    "queued": {
      "tier": "pro",
      "startsAt": "2026-11-05T10:13:00.000Z",
      "endsAt": "2026-11-05T10:13:00.000Z"
    },
    "failedPayment": false,
    "trialing": true
  },
  "balance": {
    "cents": 12,
    "periodDays": 12
  },
  "baseTrial": {
    "days": 12,
    "eligible": true,
    "refused": true
  },
  "usage": {
    "daily": 12,
    "dailyUsed": 12,
    "monthly": 12,
    "monthlyUsed": 12,
    "push": {
      "slots": 12,
      "used": 12
    },
    "exports": {
      "cap": 12,
      "used": 12
    },
    "lookups": {
      "cap": 12,
      "usedToday": 12
    }
  },
  "trial": {}
}