Skip to content

Plans & billing API ​

SaaS edition only.

All paths are relative to https://your-site.com/api/v1. Send Authorization: Bearer <token> and Accept: application/json; see authentication and errors.

MethodPathWhat it does
GET/planThe account's plan and its use of every limited feature
GET/plansEvery plan (administrators), with the feature catalogue
POST/plansCreate a plan (administrators)
PATCH/plans/{plan}Change a plan (administrators)
DELETE/plans/{plan}Delete a plan (not the default one, not one accounts are on)
GET/organizations/{organization}/planThe plan an administrator assigned to an account, and the plan it is on now (administrators)
PUT/organizations/{organization}/planPut an account on a plan, overriding what it pays for (administrators)
POST/organizations/{organization}/plan/customPut an account on its own custom plan (administrators)
GET/billingPlan, subscription and the plans that can be bought
POST/billing/checkoutPay for a plan (or switch a running subscription)
GET/billing/paddle/{transaction}A started Paddle checkout (for the /pay/paddle page)
POST/billing/portalThe provider's billing portal (card, invoices, cancellation)
POST/billing/cancelCancel at the end of the paid period
POST/billing/resumeUndo a cancellation while the period runs

GET /plan ​

The account's plan and its use of every limited feature

Responses ​

  • 200 — Plan, where it comes from, and features (limit null = unlimited; used null = not counted).
Response fields
FieldTypeRequiredDescription
dataobject
data.planobject
data.plan.idinteger
data.plan.namestring
data.plan.price_centsinteger
data.plan.yearly_price_centsinteger, nullablePrice per year (null = monthly only).
data.plan.currencystring
data.plan.limitsobject
data.plan.is_defaultboolean
data.plan.sortinteger
data.plan.accountsintegerAdministrators only.
data.plan.price_idsobjectAdministrators only.
data.plan.custom_forinteger, nullableAdministrators only: the account a custom plan was made for (null: a public plan).
data.sourcestringWhere the plan comes from: assigned by an administrator, paid, a free trial, the default (or after a trial the free) plan, or ended: the trial ended without a free plan, so no plan and nothing new is recorded. One of: override, subscription, trial, ended, default.
data.trial_ends_atstring (date-time), nullableEnd of the free trial (source trial).
data.featuresobject[]
data.features[].keystring
data.features[].labelstring
data.features[].limitinteger, nullable
data.features[].usedinteger, nullable
bash
curl -X GET "https://your-site.com/api/v1/plan" \
  -H "Authorization: Bearer $REPLORA_TOKEN" \
  -H "Accept: application/json"

GET /plans ​

Every plan (administrators), with the feature catalogue

Responses ​

  • 200 — Plans; meta.features maps feature keys to labels.
  • 403 — Not allowed (not an administrator, or outside the token's abilities).
Response fields
FieldTypeRequiredDescription
dataobject[]
data[].idinteger
data[].namestring
data[].price_centsinteger
data[].yearly_price_centsinteger, nullablePrice per year (null = monthly only).
data[].currencystring
data[].limitsobject
data[].is_defaultboolean
data[].sortinteger
data[].accountsintegerAdministrators only.
data[].price_idsobjectAdministrators only.
data[].custom_forinteger, nullableAdministrators only: the account a custom plan was made for (null: a public plan).
metaobject
meta.featuresobject
bash
curl -X GET "https://your-site.com/api/v1/plans" \
  -H "Authorization: Bearer $REPLORA_TOKEN" \
  -H "Accept: application/json"

POST /plans ​

Create a plan (administrators)

Request body ​

application/json, required

FieldTypeRequiredDescription
namestringAt most 80 characters.
price_centsintegerMinimum 0.
yearly_price_centsinteger, nullableMinimum 0.
currencystringAt least 3 characters. At most 3 characters.
price_idsobject
price_ids.stripestring, nullable
price_ids.stripe_yearlystring, nullable
price_ids.paddlestring, nullable
price_ids.paddle_yearlystring, nullable
limitsobject
is_defaultboolean
sortinteger

Responses ​

  • 201 — Created.
  • 403 — Not allowed (not an administrator, or outside the token's abilities).
  • 422 — Validation failed.
bash
curl -X POST "https://your-site.com/api/v1/plans" \
  -H "Authorization: Bearer $REPLORA_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name":"text","price_cents":0,"yearly_price_cents":0,"currency":"text","price_ids":{"stripe":"text","stripe_yearly":"text","paddle":"text","paddle_yearly":"text"},"limits":{},"is_default":true,"sort":1}'

PATCH /plans/{plan} ​

Change a plan (administrators)

Parameters ​

NameInTypeRequiredDescription
planpathintegeryes

Request body ​

application/json

FieldTypeRequiredDescription
namestringAt most 80 characters.
price_centsintegerMinimum 0.
yearly_price_centsinteger, nullableMinimum 0.
currencystringAt least 3 characters. At most 3 characters.
price_idsobject
price_ids.stripestring, nullable
price_ids.stripe_yearlystring, nullable
price_ids.paddlestring, nullable
price_ids.paddle_yearlystring, nullable
limitsobject
is_defaultboolean
sortinteger

Responses ​

  • 200 — The plan.
  • 403 — Not allowed (not an administrator, or outside the token's abilities).
  • 422 — Validation failed.
bash
curl -X PATCH "https://your-site.com/api/v1/plans/{plan}" \
  -H "Authorization: Bearer $REPLORA_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name":"text","price_cents":0,"yearly_price_cents":0,"currency":"text","price_ids":{"stripe":"text","stripe_yearly":"text","paddle":"text","paddle_yearly":"text"},"limits":{},"is_default":true,"sort":1}'

DELETE /plans/{plan} ​

Delete a plan (not the default one, not one accounts are on)

Parameters ​

NameInTypeRequiredDescription
planpathintegeryes

Responses ​

  • 204 — Deleted.
  • 422 — The default plan, or accounts are on it.
bash
curl -X DELETE "https://your-site.com/api/v1/plans/{plan}" \
  -H "Authorization: Bearer $REPLORA_TOKEN" \
  -H "Accept: application/json"

GET /organizations/{organization}/plan ​

The plan an administrator assigned to an account, and the plan it is on now (administrators)

Parameters ​

NameInTypeRequiredDescription
organizationpathintegeryes

Responses ​

  • 200 — data: {assigned: {plan_id, until (date-time or null)} or null, plan (name or null), source (override, subscription, trial, ended, default), custom_plan (the account's own custom plan, as in GET /plans, or null)}
  • 403 — Not allowed (not an administrator, or outside the token's abilities).
  • 404 — Missing, or another account's.
bash
curl -X GET "https://your-site.com/api/v1/organizations/{organization}/plan" \
  -H "Authorization: Bearer $REPLORA_TOKEN" \
  -H "Accept: application/json"

PUT /organizations/{organization}/plan ​

Put an account on a plan, overriding what it pays for (administrators)

Parameters ​

NameInTypeRequiredDescription
organizationpathintegeryes

Request body ​

application/json, required

FieldTypeRequiredDescription
plan_idinteger, nullableyesA public plan or this account's custom plan; null removes the assignment. Moving the account off its custom plan deletes that plan.
untilstring (date), nullableOptional last day (YYYY-MM-DD, today or later); afterwards the account is back on what it pays for, its trial or the free plan. null = until changed.

Responses ​

  • 200 — The new state, as GET.
  • 403 — Not allowed (not an administrator, or outside the token's abilities).
  • 404 — Missing, or another account's.
bash
curl -X PUT "https://your-site.com/api/v1/organizations/{organization}/plan" \
  -H "Authorization: Bearer $REPLORA_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"plan_id":1,"until":"2026-11-20"}'

POST /organizations/{organization}/plan/custom ​

Put an account on its own custom plan (administrators)

A copy of the plan the account is on now (or the default plan), named after the account, not for sale online and offered to no other account, assigned at once; set its limits with PATCH /plans/{plan}. Answers the account's existing custom plan when it has one. It is deleted when the account moves to another plan or is deleted.

Parameters ​

NameInTypeRequiredDescription
organizationpathintegeryes

Responses ​

  • 201 — The custom plan.
  • 403 — Not allowed (not an administrator, or outside the token's abilities).
  • 404 — Missing, or another account's.
Response fields
FieldTypeRequiredDescription
dataobject
data.idinteger
data.namestring
data.price_centsinteger
data.yearly_price_centsinteger, nullablePrice per year (null = monthly only).
data.currencystring
data.limitsobject
data.is_defaultboolean
data.sortinteger
data.accountsintegerAdministrators only.
data.price_idsobjectAdministrators only.
data.custom_forinteger, nullableAdministrators only: the account a custom plan was made for (null: a public plan).
bash
curl -X POST "https://your-site.com/api/v1/organizations/{organization}/plan/custom" \
  -H "Authorization: Bearer $REPLORA_TOKEN" \
  -H "Accept: application/json"

GET /billing ​

Plan, subscription and the plans that can be bought

Responses ​

  • 200 — Billing overview. provider null = payments not set up.
Response fields
FieldTypeRequiredDescription
dataobject
data.providerstring, nullable
data.planobject
data.plan.idinteger
data.plan.namestring
data.plan.price_centsinteger
data.plan.yearly_price_centsinteger, nullablePrice per year (null = monthly only).
data.plan.currencystring
data.plan.limitsobject
data.plan.is_defaultboolean
data.plan.sortinteger
data.plan.accountsintegerAdministrators only.
data.plan.price_idsobjectAdministrators only.
data.plan.custom_forinteger, nullableAdministrators only: the account a custom plan was made for (null: a public plan).
data.sourcestringWhere the plan comes from: assigned by an administrator, paid, a free trial, the default (or after a trial the free) plan, or ended: the trial ended without a free plan, so no plan and nothing new is recorded. One of: override, subscription, trial, ended, default.
data.trial_ends_atstring (date-time), nullableEnd of the free trial (source trial).
data.subscriptionobject, nullable
data.subscription.price_idstring, nullable
data.subscription.statusstringOne of: active, past_due, canceled, ended.
data.subscription.ends_atstring (date-time), nullable
data.portalbooleanThe billing portal can be opened.
data.plansobject[]
data.plans[].idinteger
data.plans[].namestring
data.plans[].price_centsinteger
data.plans[].yearly_price_centsinteger, nullablePrice per year (null = monthly only).
data.plans[].currencystring
data.plans[].limitsobject
data.plans[].is_defaultboolean
data.plans[].sortinteger
data.plans[].accountsintegerAdministrators only.
data.plans[].price_idsobjectAdministrators only.
data.plans[].custom_forinteger, nullableAdministrators only: the account a custom plan was made for (null: a public plan).
data.plans[].purchasableboolean
data.plans[].purchasable_yearlyboolean
bash
curl -X GET "https://your-site.com/api/v1/billing" \
  -H "Authorization: Bearer $REPLORA_TOKEN" \
  -H "Accept: application/json"

POST /billing/checkout ​

Pay for a plan (or switch a running subscription)

Answers {type: "redirect", url}: open the provider's checkout page (in the app: a browser tab; with Paddle it is this site's /pay/paddle page, which needs no sign-in). Afterwards the provider returns to return_url with checkout=done; the plan changes when the provider's webhook confirms the payment (poll GET /billing). With a running subscription the answer is {type: "swapped"}. interval yearly needs a plan with a yearly price (purchasable_yearly in GET /billing).

Request body ​

application/json, required

FieldTypeRequiredDescription
plan_idintegeryes
intervalstringOne of: monthly, yearly. Default "monthly".
return_urlstringWhere the provider sends the person back. This site, or a prefix in REPLORA_APP_RETURN_URLS (the app's deep link, e.g. replora://billing).

Responses ​

  • 200 — Where to go next.
  • 422 — Validation failed.
Response fields
FieldTypeRequiredDescription
dataobject
data.typestringOne of: redirect, swapped.
data.urlstring
bash
curl -X POST "https://your-site.com/api/v1/billing/checkout" \
  -H "Authorization: Bearer $REPLORA_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"plan_id":1,"interval":"monthly","return_url":"text"}'

GET /billing/paddle/{transaction} ​

A started Paddle checkout (for the /pay/paddle page)

Only when Paddle takes the payments (BILLING_PROVIDER=paddle). No sign-in needed. Paddle.js's client-side token and environment, and where to send the person after paying or closing the checkout (chosen by the server when the checkout started). 404 when unknown or older than a day.

No sign-in needed

This endpoint is public.

Parameters ​

NameInTypeRequiredDescription
transactionpathstringyesPattern ^txn_[A-Za-z0-9]{8,64}$.

Responses ​

  • 200 — The checkout.
  • 404 — Missing, or another account's.
Response fields
FieldTypeRequiredDescription
dataobject
data.transactionstring
data.tokenstring
data.environmentstringOne of: sandbox, production.
data.success_urlstring
data.cancel_urlstring
bash
curl -X GET "https://your-site.com/api/v1/billing/paddle/{transaction}" \
  -H "Authorization: Bearer $REPLORA_TOKEN" \
  -H "Accept: application/json"

POST /billing/portal ​

The provider's billing portal (card, invoices, cancellation)

Request body ​

application/json

FieldTypeRequiredDescription
return_urlstringWhere the provider sends the person back. This site, or a prefix in REPLORA_APP_RETURN_URLS (the app's deep link, e.g. replora://billing).

Responses ​

  • 200 — The portal URL.
  • 422 — The account has never paid.
Response fields
FieldTypeRequiredDescription
dataobject
data.urlstring
bash
curl -X POST "https://your-site.com/api/v1/billing/portal" \
  -H "Authorization: Bearer $REPLORA_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"return_url":"text"}'

POST /billing/cancel ​

Cancel at the end of the paid period

Responses ​

  • 204 — Cancelled.
  • 422 — Validation failed.
bash
curl -X POST "https://your-site.com/api/v1/billing/cancel" \
  -H "Authorization: Bearer $REPLORA_TOKEN" \
  -H "Accept: application/json"

POST /billing/resume ​

Undo a cancellation while the period runs

Responses ​

  • 204 — Resumed.
  • 422 — Validation failed.
bash
curl -X POST "https://your-site.com/api/v1/billing/resume" \
  -H "Authorization: Bearer $REPLORA_TOKEN" \
  -H "Accept: application/json"

Replora: see what your visitors see.