Amend purchases and settle their price difference

Purpose

A customer’s replacement purchase or later discount is recorded as a separate change to the original sale. The result explains both what changed and how the difference settles.

How It Works

The requester identifies the original purchase and the desired replacement or change. Its owning application supplies the allowed change and pricing basis. Commerce assembles the prorated value, tax and linked change order. Payment and delivery complete the replacement where the plan requires them. Staff can also use the amendment process for an authorized promotion applied after placement. Refused or withdrawn changes leave an explanation attached to the original order.

Relationships

Placement and billing create the linked change order, selling applications execute the replacement, and promotion evaluation supplies later discount allocations.

Show evidence (sources, provenance, origins, pinned commits)

The Formal Contract

The narrative above explains; the sections below are authoritative — the rules, scenarios and tests this document binds.

Outcomes: A remaining-months upgrade charges the difference appropriate to the unexpired term.A later promotion returns the allocated saving through credit or refund.
Surfaces: consoleportalapi
Intent sources: services-commerce:docs/migrations/post-purchase/README.md#D-P7-33services-commerce:docs/milestones/COMM-M1-set-up-what-you-sell.md#D12-F1

Controls

25 controls apply, from the corpus control catalogue.

TC-AZ-001 TC-AZ-002 TC-AZ-003 TC-AZ-004 TC-AZ-005 TC-AZ-006 TC-TEN-001 TC-TEN-002 TC-TEN-003 TC-CRY-001 TC-CRY-004 TC-DAT-001 TC-DAT-002 TC-DAT-003 TC-DAT-004 TC-LOG-001 TC-LOG-002 TC-LOG-003 TC-LOG-004 TC-LOG-005 TC-PI-001 TC-PI-003 TC-PI-005 TC-PRV-001 TC-PRV-002

Permissions

Key	Checked at	Scope
`commerce.amendments.read`	api	tenant
`commerce.amendments.create`	api	tenant
`commerce.amendments.update`	api	tenant
`commerce.amendments.approve`	api	tenant
`commerce.amendments.override`	service	tenant
`commerce.amendments.apply-promotion`	api	tenant

Business Rules

13 rules, 13 to be proved before approval. A rule's product intent is derived from its origin: 0 confirmed by a product decision, the rest inheriting this capability's proposed.

Id	Rule	Kind	Enforced at	Provenance
`01`must prove Proposed	A remaining-months change credits the original unused value, prices the replacement for the remaining term and places a linked change order for the difference using the original parties. ✓ A six-month remainder on a three-hundred-dollar annual purchase upgraded to four hundred fifty dollars credits one hundred fifty and charges two hundred twenty-five, leaving seventy-five due.✗ A request to amend the resulting change order is refused. no proof recorded yet	calculation	service	test services-commerce:modules/orders/tests/e2e/amendments.e2e.spec.js#prorates by remaining months (six of twelve): $150.00 unused, $225.00 for the rest of the term, net $75.00 charged
`02`must prove Proposed	The original line retains its amendment and successor connection, its earlier delivery is superseded and the change completes after acceptance and delivery of the replacement work. no proof recorded yet	lifecycle	service	test services-commerce:modules/orders/tests/e2e/amendments.e2e.spec.js#completes once the buyer’s card accepts the change order and the worker delivers the modify: the original fulfilment superseded
`03`must prove Proposed	A downgrade credits its negative difference and accepts the linked change order without a further payment. no proof recorded yet	calculation	service	test services-commerce:modules/orders/tests/e2e/amendments.e2e.spec.js#credits $225.00 unused against $150.00 new: net −$75.00 as a credit; the change order accepted at once, the document executing
`04`must prove Proposed	Change-order tax applies to the replacement value and returns the unused original tax share, so settlement includes the tax on both sides. origin: services-commerce:docs/migrations/post-purchase/README.md#D-P7-33 no proof recorded yet	calculation	service	test services-commerce:modules/orders/tests/e2e/amendments.e2e.spec.js#shows the tax on both sides in the plan: $18.56 on the new value, $12.38 of the original tax unused, the net $81.18
`05`must prove Proposed	A refused change leaves the original line open, while a change needing approval blocks overlapping requests until staff approve and execute it. no proof recorded yet	policy	service	test services-commerce:modules/orders/tests/e2e/amendments.e2e.spec.js#holds a change the participant wants approved; a second request on the line is 409; the approver approves, staff execute
`06`must prove Proposed	Amending a change order or requesting an unknown replacement is refused, as are unauthorized parties and access from another workspace. no proof recorded yet	validation	api, service	test services-commerce:modules/orders/tests/e2e/amendments.e2e.spec.js#refuses a change order itself (409 order_not_amendable), an unknown product (409 product_not_found), another member, a reader and another tenant
`07`must prove Proposed	Authorized console staff can apply a promotion after placement with a reason, crediting the allocated discounts and refunding freed payments or reducing an unpaid terms balance. no proof recorded yet	permission	api, service	test services-commerce:modules/orders/tests/e2e/apply-promotion-amendment.e2e.spec.js#answers 200 with the apply_promotion amendment completed, its plan on the document, its net owed to the buyer
`08`must prove Proposed	After-sale non-combining promotions compare against the stored Standard price and cannot run on older orders missing that price basis. origin: services-commerce:docs/milestones/COMM-M1-set-up-what-you-sell.md#D12-F1 no proof recorded yet	calculation	service	test services-commerce:modules/orders/tests/e2e/promotion-alternatives.e2e.spec.js#applies STD30 after placement on the lower of her $18.00 and the Standard $25.00 less 30 %, $17.50: she saves $0.50, not both
`09`must prove Proposed	Invalid, exhausted, already applied or non-qualifying codes leave only a rejected amendment and move no money. no proof recorded yet	validation	service	test services-commerce:modules/orders/tests/e2e/apply-promotion-amendment.e2e.spec.js#refuses an exhausted code code_exhausted, after its one use on another order, with nothing written but the rejected document
`10`must prove Proposed	Eligibility-restricted promotions currently lack an after-sale eligibility verdict and are refused on placed orders. no proof recorded yet	policy	service	documented services-commerce:docs/milestones/plans/COMM-M2-D10-report.md#Decisions for Andrew / follow-ups
`11`must prove Proposed	An approved amendment can be withdrawn before execution without closing the original line. no proof recorded yet	lifecycle	service	test services-commerce:modules/orders/tests/e2e/amendments.e2e.spec.js#lets the member withdraw an approved, unexecuted change; the line stays open
`12`must prove Proposed	Voiding an order also releases redemption introduced by an after-sale promotion. no proof recorded yet	lifecycle	service	test services-commerce:modules/orders/tests/e2e/apply-promotion-amendment.e2e.spec.js#releases the amendment’s redemption order_voided, as the void releases a placement’s
`13`must prove Proposed	Proration follows the declared method and value basis, limits minimum upgrade fees to a positive net and rejects time-based calculations without a valid finite term or within-term effective date. no proof recorded yet	calculation	service	observed services-commerce:modules/orders/services/amendments/proration.ts:prorate

Scenarios

Id	Given	When	Then	Provenance
`01`	A Professional member requests Premier for the rest of the term.	They pay the linked change order.	The planned difference uses the remaining term and the application completes the upgrade.	unknown FND-COM-ORD-032

Planning

Amend purchases and settle their price difference ​

Purpose ​

How It Works ​

Relationships ​