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 vairant 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
}

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 used 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.