Subscriptions and plan changes
Read and manage subscriptions over the API, price versions and version history, plan changes with an impact preview, retirement and entitlements.
All routes below take Authorization: Bearer ptk_.... Subscription ids start with sub_.
Read
curl "https://rempayments.com/api/orgs/1/subscriptions?status=active&app=3" -H "Authorization: Bearer $PTK"
curl https://rempayments.com/api/subscriptions/sub_8f2c... -H "Authorization: Bearer $PTK"A subscription carries status (incomplete, trialing, active, past_due, paused, halted, cancelled, expired), managed_by (provider when Razorpay, Stripe or PayPal bills it; hub when REM Payments issues renewal invoices), amount per period (after discount, before tax), current_period_start, current_period_end, cycles_done, cancel_at_period_end, its price_version, and pending when a price change is scheduled. The single-object answer adds timeline, payments, invoices and version_history.
Manage
Route | Scope | Body / notes |
|---|---|---|
| write |
|
| write | from |
| write | from |
| write | hub-billed only; issues an invoice with |
| read | the price-version periods: version, from, to, what moved it ( |
Price versions and plan changes
A plan's price and feature values live in price versions; every subscription is pinned to the version it bought. A PATCH /api/plans/{id} that changes the price while customers are on the plan is refused with 409 choose_how. Preview the change, then make it:
curl -X POST https://rempayments.com/api/plans/12/changes/preview -H "Authorization: Bearer $PTK" \
-H "Content-Type: application/json" \
-d '{"amount": 99900, "mode": "next_renewal", "notice_days": 30}'
curl -X POST https://rempayments.com/api/plans/12/changes -H "Authorization: Bearer $PTK" \
-H "Content-Type: application/json" \
-d '{"amount": 99900, "mode": "next_renewal", "notice_days": 30, "note": "New price from January"}'
| Existing customers |
|---|---|
| keep their version; new purchases get the new one |
| move at their first renewal on or after now + |
| move now; an increase or a feature reduction needs |
The preview (also stored on the change) gives customers on the plan by status, how many move or keep theirs, how many are moved at a gateway or fall back, MRR now and after per currency, the effective dates, features added and reduced, warnings, and blocked when the change cannot be saved.
Subscriptions billed by Razorpay, Stripe or PayPal are moved through the gateway at their switch date, because a gateway plan's price cannot be edited: each version keeps its own gateway plan (Razorpay PATCH /v1/subscriptions/{id} with schedule_change_at: cycle_end, PayPal revise, Stripe item price swap with proration_behavior=none). Our record moves when the gateway confirms. If the gateway refuses, the subscription is set to cancel at cycle end and the customer is e-mailed a link to subscribe at the new price (subscription.gateway_switch_fallback).
Other plan routes: GET /api/plans/{id}/versions, GET /api/plans/{id}/usage, POST /api/plans/{id}/retire and /unretire, archive / unarchive, DELETE /api/plans/{id} (only a plan never used; otherwise 409 plan_in_use with the facts).
Entitlements
If your app publishes a feature manifest (GET <your app>/api/payments/features, read with the link token), REM Payments answers what a customer may use:
curl "https://rempayments.com/api/link/3/entitlements?external_id=u_42" -H "Authorization: Bearer <link token>"Per feature: the value from the customer's live plans (flags OR-ed, limits and allowances the highest), else the feature's default. entitlements.changed is sent when that changes.
Last updated 18 Nov 2026