Amendments

What are amendments?

An amendment within bframe refers to a scheduled change to a contract or a pricebook. This is most commonly used to evolve terms and conditions over time. Amendments are different than edits because they do not overwrite the underlying model. Instead they are created with an effective period which determines which models are active at a specific point in time. This design necessitates additional overhead to set an effective date range, but it allows for coexistence between each iteration of the pricebook or contract. Thus bframe respects prior terms and conditions when generating invoices, line items and rated events across time.

Amendments are recognized when the durable_id is the same between multiple rows with non-overlapping effective_at and ineffective_at timestamps. In the diagram below it’s shown what this could look like for a pricebook with an amendment.

Why are amendments important?

Amendments are the safest way to make changes within a business model. The two main benefits that amendments offer are as follows:

1. Their capacity to be scheduled on a specified date.

2. They do not overwrite prior models allowing for the transformation layer to respect historical configurations.

How do amendments work in bframe?

Amending a contract or pricebook is more overhead than making an edit. For an amendment to work, the entity being changed must have an effective time range. This range is represented by the effective_at and ineffective_at fields. On model creation the ineffective_at date is often unknown and is left as NULL. If this is the case, the model must first be edited to set the ineffective_at before the amended model can be inserted. Once an effective time range has been set, a new row is then created with a consecutive non-overlapping effective range along with other modifications.

To demonstrate an amendment let’s make a modification to an enterprise contract for one of the customers in the Wikipedia case study.

Making an amedment

To make an amendment to a contract we first need a target. For this example let’s use the contract in place for the customer Scann.

Result

customers.id	customers.name	contracts.durable_id	contracts.started_at	contracts.ended_at	contracts.effective_at	contracts.ineffective_at	contracts.pricebook_id
1019	Scann	Scann_contract	2023-11-01 01:08:54	2024-11-01	2023-11-01 01:08:54		a

Query

SELECT
    cu.id AS 'customers.id',
    cu.name AS 'customers.name',
    c.durable_id AS 'contracts.durable_id',
    c.started_at AS 'contracts.started_at',
    c.ended_at AS 'contracts.ended_at',
    c.effective_at AS 'contracts.effective_at',
    c.ineffective_at AS 'contracts.ineffective_at',
    c.pricebook_id AS 'contracts.pricebook_id'
FROM bframe.customers AS cu
JOIN bframe.contracts AS c ON c.customer_id = cu.durable_id
WHERE cu.durable_id = 'Scann'

The contract that is currently in place doesn’t have an ineffective_at, so this will need to change in order for us to make an amendment. We will change the ineffective_at timestamp to be 2/1/2024.

Query

INSERT INTO src.contracts (org_id, env_id, branch_id, id, durable_id, customer_id, pricebook_id, started_at, ended_at, effective_at, ineffective_at, version) values (2, 2, 1, 1019, 'Scann_contract', 'Scann', 'a', '2023-11-01T01:08:54', '2024-11-01', '2023-11-01T01:08:54', '2024-02-01', 1);

Result

Count
1

Now that the target contract is ready, let’s amend the pricing to be discounted by 50%.

Query

INSERT INTO src.contracts (org_id, env_id, branch_id, id, durable_id, customer_id, pricebook_id, started_at, ended_at, effective_at) values (2, 2, 1, 888, 'Scann_contract', 'Scann', 'a', '2023-11-01T01:08:54', '2024-11-01', '2024-02-01');
INSERT INTO src.contract_prices (org_id, env_id, branch_id, id, list_price_uid, contract_uid, price) values (2, 2, 1, 888, 1, 888, '0.05');
INSERT INTO src.contract_prices (org_id, env_id, branch_id, id, list_price_uid, contract_uid, price) values (2, 2, 1, 889, 2, 888, '0.025');
INSERT INTO src.contract_prices (org_id, env_id, branch_id, id, list_price_uid, contract_uid, price) values (2, 2, 1, 890, 3, 888, '500.00');

Result

Count
1

Exploring the change

Now that the amendment has been put in place let’s observe the generated invoices and line items associated with this contract.

Result

products.id	products.name	line_items.quantity	prices.price	line_items.amount	line_items.invoice_delivery	line_items.status	line_items.contract_id	line_items.started_at	line_items.ended_at
1	Updates	835.0	0.05	41.75	ARREARS	FINALIZED	Scann_contract	2024-02-01	2024-03-01
2	Creates	214592.0	0.025	5364.8	ARREARS	FINALIZED	Scann_contract	2024-02-01	2024-03-01
1	Updates	1584.0	0.05	79.2	ARREARS	FINALIZED	Scann_contract	2024-03-01	2024-04-01
2	Creates	517264.0	0.025	12931.6	ARREARS	FINALIZED	Scann_contract	2024-03-01	2024-04-01
1	Updates	247.0	0.05	12.35	ARREARS	FINALIZED	Scann_contract	2024-04-01	2024-05-01
2	Creates	0.0	0.025	0.0	ARREARS	FINALIZED	Scann_contract	2024-04-01	2024-05-01
1	Updates	24.0	0.05	1.2	ARREARS	DRAFT	Scann_contract	2024-05-01	2024-06-01
2	Creates	0.0	0.025	0.0	ARREARS	DRAFT	Scann_contract	2024-05-01	2024-06-01

Query

SELECT
    prod.id as 'products.id',
    prod.name as 'products.name',
    li.quantity as 'line_items.quantity',
    price.price as 'prices.price',
    li.amount as 'line_items.amount',
    li.invoice_delivery as 'line_items.invoice_delivery',
    li.status as 'line_items.status',
    li.contract_id as 'line_items.contract_id',
    li.started_at as 'line_items.started_at',
    li.ended_at as 'line_items.ended_at'
FROM bframe.line_items AS li
JOIN bframe.contracts AS c
    ON c.durable_id = li.contract_id
JOIN bframe.products AS prod
    ON li.product_uid = prod.id
JOIN bframe.prices AS price
    ON c.id = price.contract_uid
    AND COALESCE(price.contract_price_uid, price.list_price_uid) = COALESCE(li.contract_price_uid, li.list_price_uid)
WHERE li.contract_id = 'Scann_contract'
ORDER BY li.started_at, li.product_uid;

Since this is an amendment the changes are only applied during the effective range. Thus the discount is only applied to months past 2/1/2024.