Create plan

post

https://api.frisbii.com/v1/plan

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

You can create plans easily via the plan management page of the Frisbii Billing and Pay dashboard. Plan creation is also accessible via the API if you need to create plans from you own system.

Body Params

name

string

required

length ≥ 1

Name of the plan

description

string

Description of the plan

vat

float

Optional vat for this plan. Account default is used if none given.

amount

int32

required

≥ 0

Amount for the plan in the smallest unit for the account currency

quantity

int32

≥ 1

Optional default quantity of the subscription plan product for new subscriptions. Default is 1.

prepaid

boolean

Subscriptions can either be prepaid where an amount is paid in advance, or the opposite. This setting only relates to handling of pause scenarios.

handle

string

required

length ≥ 1

Per account unique handle for the subscription plan. Max length 255 with allowable characters [a-zA-Z0-9_.-@].

currency

string

Currency for the subscription plan in ISO 4217 three letter alpha code. If not provided the account default currency will be used.

metadata

object

Custom metadata.

dunning_plan

string

Dunning plan by handle to use for the subscription plan. Default dunning plan will be used if none given.

tax_policy

string

Optional tax policy handle for this plan. If vat and tax policy is given, vat will be ignored.

renewal_reminder_email_days

int32

≥ 1

Optional renewal reminder email settings. Number of days before next billing to send a reminder email.

trial_reminder_email_days

int32

≥ 1

Optional end of trial reminder email settings. Number of days before end of trial to send a reminder email.

partial_period_handling

string

enum

How to handle a potential initial partial billing period for fixed day scheduling. The options are to bill for a full period, bill prorated for the partial period, bill a zero amoumt, or not to consider the period before first fixed day a billing period. The default is to bill prorated. Options: bill_full, bill_prorated, bill_zero_amount, no_bill.

Allowed:

include_zero_amount

boolean

Whether to add a zero amount order line to subscription invoices if plan amount is zero or the subscription overrides to zero amount. The default is to not include the line. If no other order lines are present the plan order line will be added.

setup_fee

int32

≥ 0

Optional one-time setup fee billed with the first invoice or as a separate invoice depending on the setting setup_fee_handling.

setup_fee_text

string

Optional invoice order text for the setup fee that

setup_fee_handling

string

How the billing of the setup fee should be done. The options are: first - include setup fee as order line on the first scheduled invoice. separate - create a separate invoice for the setup fee, is appropriate if first invoice is not in conjunction with creation. separate_conditional - create a separate invoice for setup fee if the first invoice is not created in conjunction with the creation. Default is first.

setup_fee_vat

float

Optional VAT for setup fee. Only returns the explicitly configured VAT rate, not the resolved rate from tax policy. Use effective_setup_fee_vat to see what will be used.

setup_fee_tax_policy

string

Optional tax policy handle for setup fee. If both setup_fee_vat and setup_fee_tax_policy are configured, tax policy takes precedence.

setup_fee_amount_incl_vat

boolean

Whether setup fee amount is including VAT. Only returns the explicitly configured value. Use effective_setup_fee_amount_incl_vat to see what will be used.

partial_proration_days

boolean

For fixed day scheduling and prorated partial handling calculate prorated amount using whole days counting start day as a full day, or use by the minute proration calculation from start date time to the next period start. Default is true (whole days).

fixed_trial_days

boolean

When using trial for fixed day scheduling use this setting to control if trial expires at midnight or the trial period is down to the minute. Default is true (trial until start of day). Trial in days can only be true if partial_proration_days is also set to true.

minimum_prorated_amount

int32

≥ 0

When using prorated partial handling the prorated amount for plan and add-ons might result in very small amounts. A minimum prorated amount for plan and add-ons can be defined. If the prorated amount is below this minimum the amount will be changed to zero.

account_funding

boolean

Indicates that Account Funding Transaction (AFT) is requested.

amount_incl_vat

boolean

Whether the amount is including VAT. Default true.

fixed_count

int32

≥ 1

Fixed number of renewals for subscriptions using this plan. Equals the number of scheduled invoices. Default is no fixed amount of renewals.

fixed_life_time_unit

string

enum

Time unit use for fixed life time

Allowed:

fixed_life_time_length

int32

1 to 12000

Optional fixed life time length for subscriptions using this plan. E.g. 12 months. Subscriptions will cancel after the fixed life time and expire when the active billing cycle ends.

trial_interval_unit

string

enum

Time unit for free trial period

Allowed:

trial_interval_length

int32

≥ 1

Optional free trial interval length. E.g. 1 monts.

interval_length

int32

1 to 12000

The length of intervals. E.g. every second month or every 14 days.

schedule_type

string

enum

required

length ≥ 1

Scheduling type, one of the following: manual, daily, weekly_fixedday, month_startdate, month_fixedday, month_lastday. See documentation for descriptions of the different types.

Allowed:

schedule_fixed_day

int32

1 to 28

If a fixed day scheduling type is used a fixed day must be provided. For months the allowed value is 1-28 for weeks it is 1-7

schedule_fixed_hour

int32

0 to 23

Fixed hour (0-23) for monthly and weekly fixed day schedules. If not null, subscription will be scheduled at this hour.

base_month

int32

1 to 12

For fixed month schedule types the base month can be used to control which months are eligible for start of first billing period. The eligible months are calculated as base_month + k * interval_length up to 12. E.g. to use quaterly billing in the months jan-apr-jul-oct, base_month 1 and interval_length 3 can be used. If not defined the first fixed day will be used as start of first billing period.

notice_periods

int32

0 to 12000

Optional number of notice periods for a cancel. The subscription will be cancelled for this number of full periods before expiring. Either from the cancellation date, or from the end of the the current period. See notice_periods_after_current. The default is to expire at the end of current period (0). A value of 1 (and notice_periods_after_current set to true) will for example result in a scenario where the subscription is cancelled until the end of current period, and then for the full subsequent period before expiring.

notice_periods_after_current

boolean

If notice periods is set, this option controls whether the number of full notice periods should start at the end of the current period, or run from cancellation date and result in a partial period with partial amount for the last period. The default is true. E.g. if set to false and notice_periods = 1 then the subscription will be cancelled for exactly for one period from the cancellation time and a partial amount will be billed at the start of the next billing period.

fixation_periods

int32

0 to 12000

Optional number of fixation periods. Fixation periods will guarantee that a subscription will have this number of paid full periods before expiring after a cancel. Default is to have no requirement (0).

fixation_periods_full

boolean

If fixation periods are defined, and the subscription can have a partial prorated first period, this parameter controls if the the last period should be full, or partial to give exactly fixation_periods paid periods. Default is false.

entitlements

array of strings

List of entitlement handles to be added to the plan

entitlements

fixation_period_unit_type

string

enum

Time unit use in conjunction with fixation periods. If not fulfilled, it falls back to fixed_life_time_unit

Allowed:

notice_period_unit_type

string

enum

Time unit used in conjunction with notice periods. If not fulfilled, it falls back to plan schedule_type

Allowed:

contract_period

int32

1 to 12000

Optional contract period length. E.g. 12 months.

contract_period_unit_type

string

enum

Time unit used for the contract period

Allowed:

contract_period_after_renewal_period

int32

1 to 12000

Optional contract period length after renewal. E.g. 6 months.

contract_period_after_renewal_unit_type

string

enum

Time unit used for the contract period after renewal

Allowed:

subscription_duration_type

string

enum

Subscription duration type

Allowed:

Responses

200Successful operation

400Invalid request, see error codes at https://api.frisbii.com/v1/error_codes

401None or invalid credentials provided in access to secured resource

403Not authorized to perform resource operation

404Resource or referenced resource not found, see error codes at https://api.frisbii.com/v1/error_codes

429Request limiting exceeded, request rate or concurrent requests, see error code 122 and 123

500Internal service error, error is reported automatically to Frisbii