Skip to content

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

POST /api/subscriptions/{id}/cancel

write

{"at_period_end": true, "reason": "..."}; sent to the gateway too

POST /api/subscriptions/{id}/pause

write

from active only

POST /api/subscriptions/{id}/resume

write

from paused only

POST /api/subscriptions/{id}/renew-now

write

hub-billed only; issues an invoice with pay_url

GET /api/subscriptions/{id}/versions

read

the price-version periods: version, from, to, what moved it (checkout, hub, gateway), amount, gateway plan id

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"}'

mode

Existing customers

new_only

keep their version; new purchases get the new one

next_renewal

move at their first renewal on or after now + notice_days (7 to 365); each gets plan.price_scheduled and an e-mail now

immediate

move now; an increase or a feature reduction needs "confirm": true (else 409 confirmation_required); the new amount applies from the next renewal

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

Subscriptions and plan changes · REM Platforms Blog