Our advanced Contract changes 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	get contract changes by id for these details	-	-
Pauses	get contract changes by id for these details	-	-
Discount subscription	get contract changes by id for these details	-	-

Example response

    {
        "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	`false`	`true`\|`false`
Component subscription	includeComponentSubscriptions	`None`	`All`\|`Changed`\|`None`
Pauses	includePauses	`None`	`All`\|`Changed`\|`None`
Discount subscription	includeDiscountSubscriptions	`None`	`All`\|`Changed`\|`None`

Example response

  {
    "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:

  <ul>
    <li>
      <code>Before</code> and <code>After</code> state for phase list and pause list:

      <ul>
        <li>here you have the ability to detect changes in these lists (e.g. has a phase/pause been added/changed),</li>
        <li>these list will change due to an active user action, whenever an order is performed or a pause has beed added/changed,</li>
        <li>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)</li>
      </ul>
    </li>
    <li>
      <code>Before</code> and <code>After</code> containing the <code>current active phase</code>:

      <ul>
        <li>ability to detect if a change has a direct effect on the current phase/pause,</li>
        <li>
          this will change on an:
          <ul>
            <li>active user change, when the start date is right now,</li>
            <li>for a timebased/scheduled change when the start date is reached.</li>
          </ul>
        </li>

        <li>this will no change if a scheduled change is added to the contract, but the start date of that change is in the future.</li>
      </ul>
    </li>
    <li>
      <code>Timestamp</code>:
      
      <ul>
        <li>indicating the point in time for this contract change,</li>
        <li>in a scenario, when a user performs an active change (order, pause change), this timestamp will be the time of the action (now),</li>
        <li>in a scenario of a scheduled change becoming active, this time will be the start date of that change.</li>
      </ul>
    </li>
    <li>
      <code>ChangeDate</code>(optional):
      
      <ul>
        <li>indicated when the change will come into effect (e.g. upgrade in the future),</li>
        <li>is typically empty for scheduled changes, when they come into affect.</li>
      </ul>
    </li>
  </ul>
</li>

Active contract changes vs scheduled changes

Overview

Immediate change

Example: an upgrade to a new plan variant that is 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:

    <ul>
      <li>Right now: phase is added, so phases list in <code>Before</code> differs from <code>After</code>, but the <code>current active phase</code> is <b>the same</b>.</li>
      <li>Month later: phases list is equal in <code>Before</code> and <code>After</code>, but the <code>current active phase</code> is <b>different</b>.</li>
    </ul>
  </li>
</ul>