--- id: CAP-COM-ORD-015 title: Amend purchases and settle their price difference feature: FEAT-COM-ORD-06 product_area: commerce module: orders revision: 1 status: draft product_intent: proposed implementation_evidence: observed supersedes: - CAP-COM-PPU-007 - CAP-COM-PPU-008 - CAP-COM-PPU-009 - CAP-COM-PPU-010 - CAP-COM-PPU-011 - CAP-COM-PPU-012 - CAP-COM-PPU-023 - CAP-COM-PPU-024 - CAP-COM-PPU-026 - CAP-COM-PRO-027 - CAP-COM-REG-037 - CAP-COM-REG-043 source_sha: services-commerce: c8b66a98e2490617aec38ba5c8165dd9bd0a8f9b react-console: baf6dae382d6f41dce976c7f848667ccc37e076f intent_sources: - 'services-commerce:docs/migrations/post-purchase/README.md#D-P7-33' - 'services-commerce:docs/milestones/COMM-M1-set-up-what-you-sell.md#D12-F1' purpose: A customer’s replacement purchase or later discount is recorded as a separate change to the original sale. outcomes: - A remaining-months upgrade charges the difference appropriate to the unexpired term. - A later promotion returns the allocated saving through credit or refund. concepts: - CON-COM-ORD-005 - CON-COM-ORD-002 actors: - ACT-COM-014 - ACT-COM-016 - ACT-COM-017 - ACT-COM-018 surfaces: - console - portal - api preconditions: [] postconditions: [] permissions: - key: commerce.amendments.read where_checked: api scope: tenant - key: commerce.amendments.create where_checked: api scope: tenant - key: commerce.amendments.update where_checked: api scope: tenant - key: commerce.amendments.approve where_checked: api scope: tenant - key: commerce.amendments.override where_checked: service scope: tenant - key: commerce.amendments.apply-promotion where_checked: api scope: tenant rules: - id: BR-CAP-COM-ORD-015-01 proved_by: [ATS-COM-ORD-008-14, ATS-COM-ORD-015-01, ATS-COM-ORD-015-15, ATS-COM-ORD-015-16, TST-COM-ORD-072] statement: >- 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. kind: calculation enforced_at: - service must_prove: true provenance: test source: >- 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 origin: none examples: positive: >- 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. negative: A request to amend the resulting change order is refused. - id: BR-CAP-COM-ORD-015-02 proved_by: [ATS-COM-ORD-015-02, TST-COM-ORD-072] statement: >- 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. kind: lifecycle enforced_at: - service must_prove: true provenance: test source: >- 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 origin: none - id: BR-CAP-COM-ORD-015-03 proved_by: [ATS-COM-ORD-015-03, TST-COM-ORD-072] statement: >- A downgrade credits its negative difference and accepts the linked change order without a further payment. kind: calculation enforced_at: - service must_prove: true provenance: test source: >- 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 origin: none - id: BR-CAP-COM-ORD-015-04 proved_by: [ATS-COM-ORD-015-04, TST-COM-ORD-072] statement: >- Change-order tax applies to the replacement value and returns the unused original tax share, so settlement includes the tax on both sides. kind: calculation enforced_at: - service must_prove: true provenance: test source: >- 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 origin: 'services-commerce:docs/migrations/post-purchase/README.md#D-P7-33' - id: BR-CAP-COM-ORD-015-05 proved_by: [ATS-COM-ORD-015-05, ATS-COM-ORD-015-14, TST-COM-ORD-072] statement: >- A refused change leaves the original line open, while a change needing approval blocks overlapping requests until staff approve and execute it. kind: policy enforced_at: - service must_prove: true provenance: test source: >- 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 origin: none - id: BR-CAP-COM-ORD-015-06 proved_by: [ATS-COM-ORD-015-06, TST-COM-ORD-072] statement: >- Amending a change order or requesting an unknown replacement is refused, as are unauthorized parties and access from another workspace. kind: validation enforced_at: - api - service must_prove: true provenance: test source: >- 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 origin: none - id: BR-CAP-COM-ORD-015-07 proved_by: [ATS-COM-ORD-004-13, ATS-COM-ORD-015-07, ATS-COM-ORD-015-13, TST-COM-ORD-074] statement: >- 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. kind: permission enforced_at: - api - service must_prove: true provenance: test source: >- 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 origin: none - id: BR-CAP-COM-ORD-015-08 proved_by: [ATS-COM-ORD-015-08, TST-COM-ORD-083] statement: >- After-sale non-combining promotions compare against the stored Standard price and cannot run on older orders missing that price basis. kind: calculation enforced_at: - service must_prove: true provenance: test source: >- 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 origin: 'services-commerce:docs/milestones/COMM-M1-set-up-what-you-sell.md#D12-F1' - id: BR-CAP-COM-ORD-015-09 proved_by: [ATS-COM-ORD-015-09, TST-COM-ORD-074] statement: >- Invalid, exhausted, already applied or non-qualifying codes leave only a rejected amendment and move no money. kind: validation enforced_at: - service must_prove: true provenance: test source: >- 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 origin: none - id: BR-CAP-COM-ORD-015-10 proved_by: [] statement: >- Eligibility-restricted promotions currently lack an after-sale eligibility verdict and are refused on placed orders. kind: policy enforced_at: - service must_prove: true provenance: documented source: 'services-commerce:docs/milestones/plans/COMM-M2-D10-report.md#Decisions for Andrew / follow-ups' origin: none note: Finding 020 records the missing post-sale audience eligibility evaluation. - id: BR-CAP-COM-ORD-015-11 proved_by: [ATS-COM-ORD-015-11, TST-COM-ORD-072] statement: An approved amendment can be withdrawn before execution without closing the original line. kind: lifecycle enforced_at: - service must_prove: true provenance: test source: >- services-commerce:modules/orders/tests/e2e/amendments.e2e.spec.js#lets the member withdraw an approved, unexecuted change; the line stays open origin: none - id: BR-CAP-COM-ORD-015-12 proved_by: [ATS-COM-ORD-015-12, TST-COM-ORD-074] statement: Voiding an order also releases redemption introduced by an after-sale promotion. kind: lifecycle enforced_at: - service must_prove: true provenance: test source: >- 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 origin: none - id: BR-CAP-COM-ORD-015-13 proved_by: [ATS-COM-ORD-015-10, TST-COM-ORD-123] statement: >- 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. kind: calculation enforced_at: - service must_prove: true provenance: observed source: 'services-commerce:modules/orders/services/amendments/proration.ts:prorate' origin: none scenarios: - id: SC-CAP-COM-ORD-015-01 given: A Professional member requests Premier for the rest of the term. when: They pay the linked change order. then: The planned difference uses the remaining term and the application completes the upgrade. provenance: unknown source: FND-COM-ORD-032 edge_cases: [] constraints: [] depends_on: - CAP-COM-ORD-006 - CAP-COM-ORD-007 - CAP-COM-ORD-012 related: - CAP-COM-ORD-004 - CAP-COM-ORD-014 journeys: [] open_questions: [] evidence: - 'Examined reference: services-commerce:docs/migrations/post-purchase/README.md#D-P7-33' - 'Examined reference: services-commerce:docs/milestones/COMM-M1-set-up-what-you-sell.md#D12-F1' - >- Examined reference: services-commerce:docs/milestones/plans/COMM-M2-D10-report.md#Decisions for Andrew / follow-ups - 'Examined reference: services-commerce:modules/orders/services/amendments/proration.ts:prorate' - >- Examined reference: 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 - >- Examined reference: 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 - >- Examined reference: 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 - >- Examined reference: services-commerce:modules/orders/tests/e2e/amendments.e2e.spec.js#lets the member withdraw an approved, unexecuted change; the line stays open - >- Examined reference: 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 - >- Examined reference: 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 - >- Examined reference: 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 - >- Examined reference: 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 - >- Examined reference: 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 - >- Examined reference: 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 - >- Examined reference: 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 controls: [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] exercised_by: [FAS-COM-ORD-06-01, FAS-COM-ORD-06-03, FAS-COM-ORD-06-04, FAS-COM-ORD-06-05] suites: [TST-COM-ORD-072, TST-COM-ORD-074, TST-COM-ORD-083, TST-COM-ORD-123] --- # 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.