Change subscription

put

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

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Plan, add-ons, amount and plan quantity can be changed either immediately or at next renewal. Typically upgrades will be done immediate and downgrades at next renewal.

A pending change at renewal will be reflected in the pending_change object on the subscription. An immediate change will cancel the pending change and a new change at renewal will replace the previous one.

To change subscription add-ons a list of subscription add-on handles to remove can be provided and a list of CreateSubscriptionAddOn objects can be provided to attach new subscription add-ons. A subscription add-on cannot be updated, but instead a remove and an attach of the same add-on can be performed. To only change add-ons immediately without any compensation or new billing, a change with add-on parameters and compensation_method=none and billing=none can be performed. An example on the use of add-ons can be found here.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Error code	HTTP code	Description
`12`	`404`	Subscription not found
`11`	`400`	Duplicate handle - Subscription add-on handle already used or multiple occurences of same handle in request
`13`	`400`	Subscription expired, must be actice or on-hold (only if not immedidate change)
`95`	`400`	Subscription on-hold and immediate change requested
`64`	`400`	Refund compensation is used but the current billing period invoice is not in required state `settled`
`65`	`400`	Refund compensation is used but the refund amount exceeds the refundable amount on the current billing period invoice. The refundable amount is the setlled invoice amount minus already refunded and credited amounts.
`82`	`400`	Credit compensation is used but the current billing period invoice is not in required state `pending`, `dunning` or `settled`
`120`	`400`	Credit compensation is used but credit amount exceeds the creditable amount on the current billing period invoice. The creditable amount is the invoice amount minus already refunded and credited amount.
`22`	`400`	Subscription cancelled
`10`	`404`	Subscription plan to change to not found
`117`	`404`	Subscription add-on to remove not found
`113`	`404`	Add-on to add not found
`114`	`400`	Add-on already added to subscription or multiple occurences of same add-on in request without explicit unique subscription add-on handle
`11`	`400`	Duplicate subscription add-on handle
`116`	`400`	Add-on to add not eligible for the subscription plan
`115`	`400`	Quantity provided for an on-off add-on
`37`	`400`	A new start date has been provided that is too far in the past
`66`	`500`	The refund compensation failed because of error at the acquirer. See `transaction_error` See transaction errors.

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