Contract Changes

Our advanced contract change API will provide you with all information about changes happening to the contract. Our contract changes have two main parts:

Contract Change API

The contract change web API will typically be used in the following scenarios:

receive a contract change by a webhook and get more details what this change is about,
get contract changes for a single contract.

Contract changes by contract

To get all contract changes for a single contract, the following endpoint can be called:

GET /contractChanges?contractId={contractId}

The following parameters can be set on this endpoint, with the same behaviour as in the contract change details API:

	Parameter name	Default	Values
Contract	includeContract	`false`	(`true`\|`false`)
Component subscription	not possible - get contract changes by id for these details
Pauses	not possible - get contract changes by id for these details
Discount subscription	not possible - get contract changes by id for these details

Example response

Simple response could look like this:

    {
        "Id": "645b6253d112e6cdaf20aa34",
        "Type": "Upgrade",
        "Timestamp": "2023-05-10T09:22:27.7710000Z",
        "OrderId": "645b625243dfd4a7292a200d",
        "ContractId": "645b60b7d112e6cdaf20a9f9",
        "ChangeDate": "2023-05-10T09:16:34.5430000Z",
        "NewPlanVariantId": "63e62a0d9864a09b6e4b2049",
        "NewPlanId": "63e62a0d9864a09b6e4b2045"
    },
    {
        "Id": "645b60b7d112e6cdaf20aa03",
        "Type": "Signup",
        "Timestamp": "2023-05-10T09:15:35.0780000Z",
        "OrderId": "645b60b73f1d6cd98d179a4a",
        "ContractId": "645b60b7d112e6cdaf20a9f9",
        "ChangeDate": "2023-05-10T09:16:34.5430000Z",
        "NewPlanVariantId": "63e62a0d9864a09b6e4b2048",
        "NewPlanId": "63e62a0d9864a09b6e4b2045"
    }

The response contains all changes of a single contract. Details of a single contract change must be accessed via the contract changes detail API.

Contract changes by id

Contract change details can be accessed using the endpoint:

GET /contractChanges/{id}

Typically, you can receive details for the following entities:

	Parameter name	Default	Values
Contract	includeContract	`true`	(`true`/`false`)
Component subscription	includeComponentSubscriptions	`None`	(`All`\|`Changed`\|`None`)
Pauses	includePauses	`None`	(`All`\|`Changed`\|`None`)
Discount subscription	includeDiscountSubscriptions	`None`	(`All`\|`Changed`\|`None`)

Example response

Simple response could look like this:

{
    "Id": "645b63b1d112e6cdaf20aa8f",
    "Type": "Upgrade",
    "Timestamp": "2023-05-10T09:28:17.1890000Z",
    "OrderId": "645b63af3e877a9fcbdf24f0",
    "ContractId": "645b60b7d112e6cdaf20a9f9",
    "ChangeDate": "2023-05-10T09:26:55.0170000Z",
    "NewPlanVariantId": "63e62a0d9864a09b6e4b2048",
    "NewPlanId": "63e62a0d9864a09b6e4b2045",
    "Contract": {
        "Id": "645b60b7d112e6cdaf20a9f9",
        "Before": {
            "CurrentPhase": {
                "Type": "Normal",
                "StartDate": "2023-05-10T09:16:34.5430000Z",
                "PlanVariantId": "63e62a0d9864a09b6e4b2049",
                "PlanId": "63e62a0d9864a09b6e4b2045",
                "Quantity": 1,
                "InheritStartDate": false
            },
            "Phases": [
                {
                    "Type": "Normal",
                    "StartDate": "2023-05-10T09:16:34.5430000Z",
                    "PlanVariantId": "63e62a0d9864a09b6e4b2049",
                    "PlanId": "63e62a0d9864a09b6e4b2045",
                    "Quantity": 1,
                    "InheritStartDate": false
                }
            ]
        },
        "After": {
            "CurrentPhase": {
                "Type": "Normal",
                "StartDate": "2023-05-10T09:26:55.0170000Z",
                "PlanVariantId": "63e62a0d9864a09b6e4b2048",
                "PlanId": "63e62a0d9864a09b6e4b2045",
                "Quantity": 1,
                "InheritStartDate": false
            },
            "Phases": [
                {
                    "Type": "Normal",
                    "StartDate": "2023-05-10T09:16:34.5430000Z",
                    "PlanVariantId": "63e62a0d9864a09b6e4b2049",
                    "PlanId": "63e62a0d9864a09b6e4b2045",
                    "Quantity": 1,
                    "InheritStartDate": false
                },
                {
                    "Type": "Normal",
                    "StartDate": "2023-05-10T09:26:55.0170000Z",
                    "PlanVariantId": "63e62a0d9864a09b6e4b2048",
                    "PlanId": "63e62a0d9864a09b6e4b2045",
                    "Quantity": 1,
                    "InheritStartDate": false
                }
            ]
        }
    }
}

Response contains the following properties:

Contract property with:
- Before and After state for phase list and pause list:
  - here you have the ability to detect changes in these lists (e.g. has a phase/pause been added/changed),
  - these list will change due to an active user action, whenever an order is performed or a pause has beed added/changed,
  - typically these lists will be identical, when there was a scheduled/timebased change to the contract (e.g. an upgrade with a start in the future has reached the start date)
- Before and After containing the current active phase:
  - ability to detect if a change has a direct effect on the current phase/pause,
  - this will change on an:
    active user change, when the start date is right now,
    for a timebased/scheduled change when the start date is reached.
  - this will no change if a scheduled change is added to the contract, but the start date of that change is in the future.
- Timestamp:
  - indicating the point in time for this contract change,
  - in a scenario, when a user performs an active change (order, pause change), this timestamp will be the time of the action (now),
  - in a scenario of a scheduled change becoming active, this time will be the start date of that change.
- ChangeDate(optional):
  - indicated when the change will come into effect (e.g. upgrade in the future),
  - is typically empty for scheduled changes, when they come into effect.

Active contract changes vs scheduled changes

Immediate change

Example: an upgrade to a new plan variant that's to take place right away,
Results in a one contract change with one phase added to the phase list, and current active phases in Before and After nodes are different.

Scheduled change (timebased)

Example: an upgrade is performed with a change date in one month,
Results in 2 contract changes:
- Right now: phase is added, so phases list in Before differs from After, but the current active phase is the same.
- Month later: phases list is equal in Before and After, but the current active phase is different.

In this section:

Welcome to our Dev Docs!