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.
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 |
| ( |
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 |
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 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 |
| ( |
Component subscription | includeComponentSubscriptions |
| ( |
Pauses | includePauses |
| ( |
Discount subscription | includeDiscountSubscriptions |
| ( |
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
andAfter
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
andAfter
containing thecurrent 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.
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
inBefore
andAfter
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 fromAfter
, but thecurrent active phase
is the same.Month later: phases list is equal in
Before
andAfter
, but thecurrent active phase
is different.