Create a Subscription Plan

POST

subscription

plan

curl -X POST https://api.therius.io/v1/subscription/plan \
  -H "Authorization: Bearer prv_production_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantCode": "MERCHANT_001",
    "name": "Pro Monthly",
    "amount": 2999,
    "currency": "USD",
    "interval": "month",
    "trialPeriodDays": 14,
    "availableCountries": ["US", "CA"]
  }'

{
  "id": 123,
  "merchantId": 123,
  "name": "<string>",
  "description": "<string>",
  "interval": "day",
  "intervalCount": 123,
  "amount": 123,
  "currency": "<string>",
  "exponent": 123,
  "trialPeriodDays": 123,
  "introAmount": 123,
  "introBillingCycles": 123,
  "maxBillingCycles": 123,
  "availableCountries": [
    "<string>"
  ],
  "isActive": true,
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z"
}

Plans define the billing terms for subscriptions — amount, currency, interval, and optional trial period. Once a plan has active subscribers, its amount, interval, intervalCount, and currency are immutable. To change pricing or cadence for existing subscribers, create a new plan and migrate them using change-plan. amount, currency, interval, and intervalCount become immutable once the plan has active subscribers — see the parameters panel above for the full field list, including the introductory-pricing (introAmount/introBillingCycles) and maxBillingCycles/availableCountries options. Returns 201 Created with the full plan object including the generated id.

curl -X POST https://api.therius.io/v1/subscription/plan \
  -H "Authorization: Bearer prv_production_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantCode": "MERCHANT_001",
    "name": "Pro Monthly",
    "amount": 2999,
    "currency": "USD",
    "interval": "month",
    "trialPeriodDays": 14,
    "availableCountries": ["US", "CA"]
  }'

Authorizations

Authorization

string

header

required

Your secret API key: Bearer prv_production_xxx (production) or Bearer prv_sandbox_xxx (sandbox).

Body

application/json

merchantCode

string

required

Your merchant account identifier.

name

string

required

Human-readable plan name.

interval

enum<string>

required

Billing interval unit.

Available options:

day,

week,

month,

year

amount

integer

required

Recurring charge in the currency minor units.

currency

string

required

ISO 4217 currency code.

description

string

Optional plan description.

intervalCount

integer

Number of interval units between charges. Defaults to 1.

exponent

integer

Decimal places for amount - defaults to the currency standard (2 for USD, 0 for JPY).

trialPeriodDays

integer

Free-trial length in days. 0 for no trial.

introAmount

integer

Introductory charge in minor units for the first introBillingCycles cycles.

introBillingCycles

integer

Cycles billed at introAmount before reverting to amount.

maxBillingCycles

integer

Total cycles after which the subscription auto-completes. 0 = open-ended.

availableCountries

string[]

ISO 3166-1 alpha-2 codes to restrict the plan to. Omit for global availability.

Response

201 - application/json

Plan created

A reusable billing plan. amount is a flat integer in the currency minor units (with separate currency + exponent) - not an Amount object.

integer

The plan unique integer ID.

merchantId

integer

The merchant account that owns the plan.

name

string

description

string

interval

enum<string>

Billing interval unit. Immutable after creation.

Available options:

day,

week,

month,

year

intervalCount

integer

Number of interval units between charges - month + 3 bills quarterly.

amount

integer

Recurring charge in the currency minor units (e.g. 2999 = $29.99 at exponent 2). Immutable after creation.

currency

string

ISO 4217 currency code. Immutable after creation.

exponent

integer

Decimal places for amount / introAmount - 2 for USD, 0 for JPY.

trialPeriodDays

integer

Free-trial length in days before the first charge. 0 for no trial.

introAmount

integer

Introductory charge in minor units for the first introBillingCycles cycles, if set.

introBillingCycles

integer

How many initial cycles are billed at introAmount before the rate reverts to amount.

maxBillingCycles

integer

Total cycles after which the subscription auto-completes. 0 = open-ended.

availableCountries

string[]

ISO 3166-1 alpha-2 codes the plan is offered in. Empty = available everywhere.

isActive

boolean

Whether the plan accepts new subscribers. Existing subscriptions are unaffected when this is false.

createdAt

string<date-time>

updatedAt

string<date-time>

curl -X POST https://api.therius.io/v1/subscription/plan \
  -H "Authorization: Bearer prv_production_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantCode": "MERCHANT_001",
    "name": "Pro Monthly",
    "amount": 2999,
    "currency": "USD",
    "interval": "month",
    "trialPeriodDays": 14,
    "availableCountries": ["US", "CA"]
  }'

{
  "id": 123,
  "merchantId": 123,
  "name": "<string>",
  "description": "<string>",
  "interval": "day",
  "intervalCount": 123,
  "amount": 123,
  "currency": "<string>",
  "exponent": 123,
  "trialPeriodDays": 123,
  "introAmount": 123,
  "introBillingCycles": 123,
  "maxBillingCycles": 123,
  "availableCountries": [
    "<string>"
  ],
  "isActive": true,
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z"
}

Payments

Tokenization

Subscriptions

Subscription Plans

SDK Session

Create a Subscription Plan

Authorizations

Body

Response