Appearance
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.
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
| Field | Type | Required | Description |
|---|---|---|---|
data | object | ||
data.plan | object | ||
data.plan.id | integer | ||
data.plan.name | string | ||
data.plan.price_cents | integer | ||
data.plan.yearly_price_cents | integer, nullable | Price per year (null = monthly only). | |
data.plan.currency | string | ||
data.plan.limits | object | ||
data.plan.is_default | boolean | ||
data.plan.sort | integer | ||
data.plan.accounts | integer | Administrators only. | |
data.plan.price_ids | object | Administrators only. | |
data.plan.custom_for | integer, nullable | Administrators only: the account a custom plan was made for (null: a public plan). | |
data.source | string | Where 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_at | string (date-time), nullable | End of the free trial (source trial). | |
data.features | object[] | ||
data.features[].key | string | ||
data.features[].label | string | ||
data.features[].limit | integer, nullable | ||
data.features[].used | integer, 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.featuresmaps feature keys to labels. - 403 — Not allowed (not an administrator, or outside the token's abilities).
Response fields
| Field | Type | Required | Description |
|---|---|---|---|
data | object[] | ||
data[].id | integer | ||
data[].name | string | ||
data[].price_cents | integer | ||
data[].yearly_price_cents | integer, nullable | Price per year (null = monthly only). | |
data[].currency | string | ||
data[].limits | object | ||
data[].is_default | boolean | ||
data[].sort | integer | ||
data[].accounts | integer | Administrators only. | |
data[].price_ids | object | Administrators only. | |
data[].custom_for | integer, nullable | Administrators only: the account a custom plan was made for (null: a public plan). | |
meta | object | ||
meta.features | object |
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
| Field | Type | Required | Description |
|---|---|---|---|
name | string | At most 80 characters. | |
price_cents | integer | Minimum 0. | |
yearly_price_cents | integer, nullable | Minimum 0. | |
currency | string | At least 3 characters. At most 3 characters. | |
price_ids | object | ||
price_ids.stripe | string, nullable | ||
price_ids.stripe_yearly | string, nullable | ||
price_ids.paddle | string, nullable | ||
price_ids.paddle_yearly | string, nullable | ||
limits | object | ||
is_default | boolean | ||
sort | integer |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
plan | path | integer | yes |
Request body
application/json
| Field | Type | Required | Description |
|---|---|---|---|
name | string | At most 80 characters. | |
price_cents | integer | Minimum 0. | |
yearly_price_cents | integer, nullable | Minimum 0. | |
currency | string | At least 3 characters. At most 3 characters. | |
price_ids | object | ||
price_ids.stripe | string, nullable | ||
price_ids.stripe_yearly | string, nullable | ||
price_ids.paddle | string, nullable | ||
price_ids.paddle_yearly | string, nullable | ||
limits | object | ||
is_default | boolean | ||
sort | integer |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
plan | path | integer | yes |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
organization | path | integer | yes |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
organization | path | integer | yes |
Request body
application/json, required
| Field | Type | Required | Description |
|---|---|---|---|
plan_id | integer, nullable | yes | A public plan or this account's custom plan; null removes the assignment. Moving the account off its custom plan deletes that plan. |
until | string (date), nullable | Optional 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
organization | path | integer | yes |
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
| Field | Type | Required | Description |
|---|---|---|---|
data | object | ||
data.id | integer | ||
data.name | string | ||
data.price_cents | integer | ||
data.yearly_price_cents | integer, nullable | Price per year (null = monthly only). | |
data.currency | string | ||
data.limits | object | ||
data.is_default | boolean | ||
data.sort | integer | ||
data.accounts | integer | Administrators only. | |
data.price_ids | object | Administrators only. | |
data.custom_for | integer, nullable | Administrators 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.
providernull = payments not set up.
Response fields
| Field | Type | Required | Description |
|---|---|---|---|
data | object | ||
data.provider | string, nullable | ||
data.plan | object | ||
data.plan.id | integer | ||
data.plan.name | string | ||
data.plan.price_cents | integer | ||
data.plan.yearly_price_cents | integer, nullable | Price per year (null = monthly only). | |
data.plan.currency | string | ||
data.plan.limits | object | ||
data.plan.is_default | boolean | ||
data.plan.sort | integer | ||
data.plan.accounts | integer | Administrators only. | |
data.plan.price_ids | object | Administrators only. | |
data.plan.custom_for | integer, nullable | Administrators only: the account a custom plan was made for (null: a public plan). | |
data.source | string | Where 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_at | string (date-time), nullable | End of the free trial (source trial). | |
data.subscription | object, nullable | ||
data.subscription.price_id | string, nullable | ||
data.subscription.status | string | One of: active, past_due, canceled, ended. | |
data.subscription.ends_at | string (date-time), nullable | ||
data.portal | boolean | The billing portal can be opened. | |
data.plans | object[] | ||
data.plans[].id | integer | ||
data.plans[].name | string | ||
data.plans[].price_cents | integer | ||
data.plans[].yearly_price_cents | integer, nullable | Price per year (null = monthly only). | |
data.plans[].currency | string | ||
data.plans[].limits | object | ||
data.plans[].is_default | boolean | ||
data.plans[].sort | integer | ||
data.plans[].accounts | integer | Administrators only. | |
data.plans[].price_ids | object | Administrators only. | |
data.plans[].custom_for | integer, nullable | Administrators only: the account a custom plan was made for (null: a public plan). | |
data.plans[].purchasable | boolean | ||
data.plans[].purchasable_yearly | boolean |
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
| Field | Type | Required | Description |
|---|---|---|---|
plan_id | integer | yes | |
interval | string | One of: monthly, yearly. Default "monthly". | |
return_url | string | Where 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
| Field | Type | Required | Description |
|---|---|---|---|
data | object | ||
data.type | string | One of: redirect, swapped. | |
data.url | string |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
transaction | path | string | yes | Pattern ^txn_[A-Za-z0-9]{8,64}$. |
Responses
- 200 — The checkout.
- 404 — Missing, or another account's.
Response fields
| Field | Type | Required | Description |
|---|---|---|---|
data | object | ||
data.transaction | string | ||
data.token | string | ||
data.environment | string | One of: sandbox, production. | |
data.success_url | string | ||
data.cancel_url | string |
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
| Field | Type | Required | Description |
|---|---|---|---|
return_url | string | Where 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
| Field | Type | Required | Description |
|---|---|---|---|
data | object | ||
data.url | string |
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"