Developer Docs

Developer Docs

  • Getting Started
  • SubscriptionJS
  • REST API
  • Webhooks
  • Code Samples
  • UseCases
  • Request a Demo

›Contracts

Introduction

  • Introduction

Contracts

  • Adding contract for new customer
  • Adding contract for existing customer
  • Adding future contract without invoicing
  • Up/-downgrading to a plan variant
  • Terminate a contract with notice
  • Terminate a contract without notice

Components

    Component subscriptions

    • Concept
    • Adding/removing
    • In-/decreasing quantity
    • Override for components

    Metered usage components

    • Concept
    • Bill metered usage
    • Override for metered usage

Discounts

  • Adding discounts
  • Adding discounts via coupon

Miscellaneous

  • Rated items
  • Email Notification Template

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.

Last updated on 8/5/2020 by AxelDuenninger
← Adding future contract without invoicingTerminate a contract with notice →
Docs
Getting StartedAPI Reference
Resource
Help CenterSupportBlogTutorials
Start with billwerk
Test for free
Request a Demo
Already started?
billwerk Sandboxbillwerk Production
billwerk GmbH
© Made with ❤ in Germany for Europe by billwerk GmbH | 2022
Imprint
|
Data Privacy Rules
|
Disclaimer