Up/-downgrading to a plan variant
If you want to change the basic subscription of a contract though an up/-downgrade, this is done via the endpoint POST /Orders. All changes to the products booked in the contract are done in the Cart. By providing a PlanVariantId the basic subscription will be changed accordingly.
By default, up-/downgrade orders are processed instantly after successful commit via POST /Orders/{id}/commit. Contract changes though up/-downgrade orders can also be realized in the future or to past by passing a ChangeDate.
Sample request up/-downgrade order
POST /Orders
{
"TriggerInterimBilling": false,
"ContractId": "5e53dab7443e5516749566e2",
"Cart": {
"PlanVariantId": "5e53dab7443e5516749566fe",
"InheritStartDate": false,
"ComponentSubscriptions": [
{
"ComponentId": "5e53dab7443e5516749566fb",
"Quantity": 2.0
}
],
"MeteredUsages": [
{
"ComponentId": "5e53dab7443e551674956701",
"Quantity": 3.0,
"Memo": "Memo text",
"Key": "Some unique external key 12345",
"DueDate": "2020-02-23T14:16:23.7556386Z"
}
],
"EndComponentSubscriptions": [
"5e53dab7443e5516749566ff",
"5e53dab7443e551674956700"
]
},
"ChangeDate": "2020-03-09T10:58:11.799Z",
"PreviewAfterTrial": false
}
An up-/downgrade to a plan variant will change future billing periods. The new billing periods will be calculated based on the billing interval defined in the new plan variant selected in the up/-downgrade as well as the ChangeDate passed in the order.
With an up-/downgrade, you can also add/remove component subscriptions and pass metered usage. Omit ComponentSubscriptions, EndComponentSubscriptions, MeteredUsages or pass an empty array if not used.
Sample response POST /Orders
{
"Id": "5e53dab7443e55167495670e",
"AllowWithoutPaymentData": true,
"ComponentSubscriptions": [
{
"ComponentType": "QuantityBased",
"PreventModification": false,
"VatPercentage": 19.0,
"TotalNet": 2.0,
"TotalVat": 0.38,
"IsQuantityBased": false,
"ComponentId": "5e53dab7443e5516749566fb",
"Quantity": 2.0
}
],
"Total": 7.0,
"TotalVat": 1.33,
"TotalGross": 0.0,
"NextTotalGross": 0.0,
"IsTrial": false,
"TrialEndPolicy": "NoTrial",
"Status": "InProgress",
"OrderType": "Signup",
"TriggerInterimBilling": false,
"CustomerId": "5e53dab7443e55167495670f",
"ContractId": "5e53dab7443e5516749566e2",
"PreviewAfterTrial": false
}
Up/-downgrading to a plan variant - selecting specific up/-downgrade date and time
If you want to up/-downgrade a contract at a specific point in time, you can do so by adding a ChangeDate.
Typically, used ChangeDate are:
- Contract start date,
- Last billing date,
- Next billing date,
- Billed until.
These can be calculated by looking at the contract using GET /Contracts/{id}.
Sample response GET /Contracts/{id}
{
"Id": "5e563b344de08409ace88ecb",
"LastBillingDate": "2020-02-26T09:32:36.1230000Z",
"NextBillingDate": "2020-03-26T09:32:36.1230000Z",
"PlanId": "5be2ecd7ba5c1e0bf4f34de6",
"CustomerId": "5e563b344de08409ace88eca",
"IsDeletable": false,
"LifecycleStatus": "Active",
"CustomerName": "test, test",
"CustomerIsLocked": false,
"Phases": [
{
"Type": "Normal",
"StartDate": "2020-02-26T09:32:36.1230000Z",
"PlanVariantId": "5cee2c964de0841b78b20fa0",
"PlanId": "5be2ecd7ba5c1e0bf4f34de6",
"Quantity": 1,
"InheritStartDate": false
}
],
"Balance": 162.98,
"ReferenceCode": "KXPL-GWBS",
"Currency": "EUR",
"PlanGroupId": "5b680208ba5c1e10084c1a9e",
"PaymentProvider": "InvoicePayment",
"PaymentProviderRole": "BlackLabel",
"EscalationSuspended": false,
"RecurringPaymentsPaused": false,
"CurrentPhase": {
"Type": "Normal",
"StartDate": "2020-02-26T09:32:36.1230000Z",
"PlanVariantId": "5cee2c964de0841b78b20fa0",
"PlanId": "5be2ecd7ba5c1e0bf4f34de6",
"Quantity": 1,
"InheritStartDate": false
},
"PaymentProviderSupportRefunds": false,
"CurrentDunning": {
"Level": 3,
"Amount": 126.5,
"Remaining": 126.5,
"Threshold": 5,
"DocumentId": "5e5b04779cc9b925200966f9",
"Timestamp": "2020-03-01T00:40:23.0000000Z",
"IsAtrigaEscalated": false
},
"BillingSuspended": false,
"ThresholdBillingDisabled": false,
"TurnoverGross": "512.98 EUR",
"TurnoverNet": "378.31 EUR",
"StartDate": "2020-02-26T09:32:36.1230000Z",
"BilledUntil": "2021-02-26T09:32:36.1230000Z",
"PlanVariantId": "5cee2c964de0841b78b20fa0",
"CustomFields": {}
}
The contract start date can be realized via the use of the StartDate from the contract, last billing and next billing date though LastBillingDate and NextBillingDate and billed until via BilledUntil.
For up/-downgrading at the end of the regular contract period, the ChangeDate can be derived from a cancellation preview as described in the Terminate a contract with notice section.
Caution
The Require Payment checkbox, that automatically fails an order if the invoice amount cannot be collected from a payment method (in the case of up- or downgrades) is only accessible via Customer Self-Service.
If the order is commited via the REST API, our system accepts the order even without payment data.
This means, that if you are using the up/-downgrade order via our SubscriptionJS (API), you as a merchant have to check the incoming payment.
Up/-downgrade to plan variant while in trial
There is a new nullable property Trial available in the cart of an order.
This can be set to the following values:
- Enabled,
- Disabled,
- ReplaceReminder.
Note
- For Signup: only Disabled and Enabled are allowed.
Signup default if null: Enabled.
- For Upgrades: all three options are allowed.
Upgrade default if null: Disabled.
ReplaceReminder will replace the current length of the trial active with the new PlanVariant booked:
Updated 9 months ago