Preview change subscription

put

https://api.frisbii.com/v1/subscription/{handle}/preview

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

A subscription change can be tried out by creating a subscription change preview. The preview does not perform any actual change but sums up what would happen if the change request was performed.

Returns a ChangedSubscription object which is the Subscription object after the change with additional parameter SubscriptionChangeJournal describing potential compensation and new billing.

Errors

The operation can generate the same errors as for a normal change operation.

Path Params

handle

string

required

Subscription handle

Body Params

timing

string

enum

required

When to perform the subscription change. Either immediate or renewal.

Allowed:

plan

string

The handle of the plan to change to

amount

int32

≥ 0

Optional custom per quantity plan price. If provided the plan price billed for each billing period will be overridden by this price.

quantity

int32

≥ 1

Optional quantity override. If not provided, the subscription's current stored quantity is preserved unchanged, regardless of the new plan's default quantity. If provided, the given value is used.

billing

string

enum

In the case of immediate change and change not affecting billing period, how to bill for the remaining partial period. Either prorated, full, zero_amount or none. The default is prorated.

Allowed:

amount_incl_vat

boolean

Whether the optional amount is including VAT. Defaults to true.

force_change_amount_incl_vat

boolean

Force a change to the amount_incl_vat setting even if the value appears unchanged. When true, the amount_incl_vat value will be explicitly set, allowing reset to plan defaults when null.

compensation_method

string

enum

For an immediate change, optional compensation: full_refund, prorated_refund, full_credit, prorated_credit, none, prorated, or full (default prorated_refund). For timing=renewal, prorated_credit and prorated_refund are always treated as prorated, and full_credit and full_refund as full, regardless of whether billing frequencies differ; stored full means refund if possible, otherwise credit. Null defaults to prorated when the change is applied.

Allowed:

partial_period_handling

string

enum

Optional argument to override plan setting on 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 amount, 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:

start_date

string

If the subscription change results in a new period due to change to a plan with different scheduling, or the use of argument force_new_period, an optional date and time from which the subscription is eligible to schedule first invoice can be given. See subscription create and subscription reactivate argument start_date. If the subscription has not yet started it's billing cycles, e.g. in trial or changing from a manual plan, start_date will default to now.

force_new_period

boolean

If an immediate change should result in a new billing period starting now, or at the optional start_date. If the subscription is in trial the trial will be terminated. Default is false. If the subscription change results in a new period due to change to a plan with different scheduling, this option will have no effect as new period is required in this case.

cancel_change

boolean

If there are pending changes at renewal for the subscription they can be cancelled using this argument and timing=renewal

add_ons

array of objects

length between 0 and 100

Add-ons to attach to subscription. The same add-on can only be attached to subscription once unless unique handles are supplied for the subscription add-on. A maximum of 100 add-ons is allowed.

add_ons

remove_add_ons

array of strings

Subscription add-ons to remove from subscription by subscription add-on handle

remove_add_ons

fixation_period_end_date

string

Date and time on the form yyyy-MM-dd, yyyyMMdd, yyyy-MM-ddTHH:mm and yyyy-MM-ddTHH:mm:ss which represents the earliest possible cancellation date

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_period_unit_type

string

enum

Time unit used in conjunction with notice periods

Allowed:

contract_period_start_date

string

Contract period start date for the subscription

contract_period_end_date

string

Contract period end date for the subscription

contract_period_after_renewal_period

int32

0 to 12000

Contract period after renewal

contract_period_after_renewal_unit_type

string

enum

Time unit for the contract period after renewal

Allowed:

Responses

Errors

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