Calculate and explain a buyer’s item price

Purpose

Commerce calculates the price appropriate to an item, subject, currency and selling context.

How It Works

A caller submits products and the pricing context needed for the calculation. Commerce qualifies audiences and selects applicable period and currency inputs before applying adjustments. The response explains selected prices, assumptions and warnings. Staff may explore hypothetical context, while portal buyers remain confined to permitted subjects. Public requests have additional storefront guards. Missing rates, prohibited products and required extension failures affect whether a price can support placement. Quoting remains read-only and placement performs its own calculation and eligibility checks.

Relationships

The configure qualifying price audiences capability supplies related configuration or assessment used in this work.

The maintain dated pricing periods capability supplies related configuration or assessment used in this work.

The configure product purchasing and price adjustments capability supplies related configuration or assessment used in this work.

The present the store’s available products capability supplies related configuration or assessment used in this work.

The choose the best permitted promotional result capability supplies related configuration or assessment used in this work.

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 buyer’s price is an identical whether customer staff preview it, a shopper browses it or a checkout charges it.Membership retains its value, and nobody is charged a price a required rule does not approved.
Surfaces: consoleportalapi
Intent sources: services-commerce:docs/milestones/COMM-M1-set-up-what-you-sell.md#D5services-commerce:docs/milestones/COMM-M1-set-up-what-you-sell.md#D8services-commerce:docs/milestones/COMM-M1-set-up-what-you-sell.md#D10services-commerce:docs/milestones/COMM-M1-set-up-what-you-sell.md#D14services-commerce:docs/milestones/COMM-M1-set-up-what-you-sell.md#D5-F1services-commerce:docs/milestones/plans/COMM-M1-plan.md#2. Scope (item 7)services-commerce:docs/milestones/plans/COMM-M1-plan.md#4. Assumptions (A11, A13, A14)

Controls

26 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-TEN-004 TC-CRY-001 TC-DAT-001 TC-DAT-002 TC-DAT-003 TC-LOG-001 TC-LOG-002 TC-LOG-003 TC-LOG-004 TC-LOG-005 TC-AVL-005 TC-PI-001 TC-PI-002 TC-PI-003 TC-PI-005 TC-PRV-001 TC-PRV-002

Permissions

Key	Checked at	Scope
`commerce.price-quotes.read`	api	tenant
`commerce.orders.create`	service	tenant

Business Rules

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

Id	Rule	Kind	Enforced at	Provenance
`01`must prove Proposed	Pricing follows entered variable amounts, qualification, audience-period selection, application adjustments, quantity adjustments, product pricing, rounding and store order pricing, with promotions and tax applied afterward. origin: COMM-M1 D5 (docs/milestones/COMM-M1-set-up-what-you-sell.md) proved by `ATS-COM-CAT-004-07`, `ATS-COM-CAT-007-11`, `ATS-COM-CAT-012-10`, `ATS-COM-CAT-013-01`, `ATS-COM-CAT-013-15`, `ATS-COM-CAT-013-18`, `ATS-COM-CAT-013-20`, `TST-COM-CAT-082`	calculation	service	test services-commerce:modules/pricing/tests/unit/engine/engine.spec.js#prices the hoodies through the member cell, the variant, the bulk rule and the store’s line discount, in that order
`02`must prove Proposed	Standard always qualifies, and active eligibility audiences qualify only on an eligible decision for the qualification date; other verdicts retain their reasons without qualification. proved by `ATS-COM-CAT-010-10`, `ATS-COM-CAT-013-02`, `ATS-COM-CAT-013-16`, `TST-COM-CAT-085`	calculation	service	test services-commerce:modules/pricing/tests/unit/engine/step-2-audience-resolution.spec.js#does not qualify for an ineligible decision, an indeterminate one, a provisional one or one under review, and says why
`03`must prove Proposed	A missing audience-period price falls back to that audience’s Always price and then another qualifying audience, ultimately Standard. origin: COMM-M1 D6 (docs/milestones/COMM-M1-set-up-what-you-sell.md) proved by `ATS-COM-CAT-011-11`, `ATS-COM-CAT-013-03`, `ATS-COM-CAT-013-17`, `TST-COM-CAT-086`	calculation	service, console	test services-commerce:modules/pricing/tests/unit/engine/step-3-base-price.spec.js#inherits the audience’s always cell when the period has none, never another period’s cell
`04`must prove Proposed	Each pricing rounding step uses whole minor currency units and moves exact halves away from zero. origin: COMM-M1 D5 (docs/milestones/COMM-M1-set-up-what-you-sell.md) proved by `ATS-COM-CAT-013-04`, `TST-COM-CAT-084`	calculation	service, console	test services-commerce:modules/pricing/tests/unit/engine/rounding.spec.js#rounds a negative half down, away from zero, where Math.round would answer -2
`05`must prove Confirmed	Computed foreign-currency prices use the base price and that day’s exchange rate, retain conversion provenance on the line and refuse pricing when the rate is missing. origin: COMM-M1 plan A14 (MP D-19) (docs/milestones/plans/COMM-M1-plan.md) proved by `ATS-COM-CAT-013-05`, `TST-COM-CAT-086`	calculation	service	test services-commerce:modules/pricing/tests/unit/engine/step-3-base-price.spec.js#converts a calculate cell from the base cell at the rate of the day, rounded half away from zero, and freezes the conversion
`06`must prove Proposed	Standard currency prohibition prevents purchase by every audience in that currency, and products outside their sale windows cannot be priced for purchase. proved by `ATS-COM-CAT-013-05`, `TST-COM-CAT-086`	validation	service	test services-commerce:modules/pricing/tests/unit/engine/step-3-base-price.spec.js#refuses a currency the product is prohibited in for everyone (a prohibit on standard)
`07`must prove Proposed	Public buyers cannot quote drafts, products without listings or products outside the store assortment; console staff with order-create permission receive the exemption. origin: COMM-M1 D8 (docs/milestones/COMM-M1-set-up-what-you-sell.md) proved by `ATS-COM-CAT-006-15`, `ATS-COM-CAT-013-06`, `TST-COM-CAT-057`	policy	service	test services-commerce:modules/pricing/tests/e2e/price-quote-public-sale.e2e.spec.js#prices the draft and the out-of-assortment product for staff holding commerce.orders.create: Standard 6000 and 15000
`08`must prove Proposed	Anonymous quotes require a store, exclude person and cart references, and return Standard and publicly displayed audience prices with the sign-in notice. origin: COMM-M1 D10 (docs/milestones/COMM-M1-set-up-what-you-sell.md) proved by `ATS-COM-CAT-008-08`, `ATS-COM-CAT-013-07`, `ATS-COM-CAT-013-19`, `TST-COM-CAT-056`, `TST-COM-CAT-060`	policy	api, service	test services-commerce:modules/pricing/tests/e2e/price-quotes.e2e.spec.js#refuses a body that names a subject, an acting contact, a recipient or a cart: nothing about a person is read anonymously
`09`must prove Proposed	Required extension failure prevents placement and records an exception; optional placement failures and quote failures skip the extension with a warning. origin: COMM-M1 D14 (docs/milestones/COMM-M1-set-up-what-you-sell.md) proved by `ATS-COM-CAT-013-08`, `TST-COM-CAT-068`, `TST-COM-CAT-087`	policy	service	test services-commerce:modules/pricing/tests/integration/services/extensions/priced-with-extensions.integration.spec.js#refuses with EXTENSION_UNAVAILABLE naming the extension, and records the exception on the order with the SDK’s status (A24)
`10`must prove Proposed	An order-pricing extension fee is refused during preview and placement while invoicing support remains unavailable, without saving the sale. origin: COMM-M1 D5-F1 (docs/milestones/COMM-M1-set-up-what-you-sell.md) proved by `ATS-COM-CAT-013-09`	policy	service	documented services-commerce:docs/milestones/COMM-M1-set-up-what-you-sell.md#D5-F1
`11`must prove Proposed	Staff may preview hypothetical audiences or dates with assumptions identified in the response, while portal buyers cannot use those overrides. proved by `ATS-COM-CAT-013-10`, `TST-COM-CAT-058`	permission	api, service	test services-commerce:modules/pricing/tests/e2e/price-quote-staff-form.e2e.spec.js#refuses a portal member either property, 403, and prices them without
`12`must prove Proposed	Portal quotes cover the buyer’s contact or an organization they may act for; organization purchasing-role results are reported per item without refusing the quote. proved by `ATS-COM-CAT-013-11`, `TST-COM-CAT-060`	permission	service	test services-commerce:modules/pricing/tests/e2e/price-quotes.e2e.spec.js#is refused a quote for another contact (403), and gets a public quote when naming nobody
`13`must prove Proposed	Quoting creates no records or price commitment, and placement recomputes the payable price. origin: COMM-M1 plan A13 (order domain D13) (docs/milestones/plans/COMM-M1-plan.md) proved by `ATS-COM-CAT-013-12`, `TST-COM-CAT-060`, `TST-COM-CAT-083`	invariant	service	test services-commerce:modules/pricing/tests/unit/engine/quote-tolerance.spec.js#differs with the changes when a price moved, never answering the previewed price
`14`must prove Proposed	Placement rechecks eligibility-audience lines in the order transaction, rejects lapsed qualification per line and marks each period’s first sale once. proved by `ATS-COM-CAT-011-11`, `ATS-COM-CAT-013-13`, `ATS-COM-CAT-013-17`, `TST-COM-CAT-081`	policy	service	test services-commerce:modules/pricing/tests/integration/services/placement/audience-settlement.integration.spec.js#refuses the placement for a lapsed member, one audience_lapsed problem per line with the portal sentence, stamping nothing
`15`must prove Proposed	Quote requests accept at most fifty items with positive integer quantities and require quote-read permission, included in every built-in role. proved by `ATS-COM-CAT-013-14`, `TST-COM-CAT-059`, `TST-COM-CAT-060`	validation	api	test services-commerce:modules/pricing/tests/e2e/price-quotes.e2e.spec.js#refuses more than fifty items

Scenarios

Id	Given	When	Then	Provenance
`01`	The guide has Standard and Member price rows	Quote for a qualified member	The response uses the eighty-dollar Member price	documented services-commerce:docs/milestones/plans/COMM-M1-plan.md#D5. The order of the price calculation
`02`	The store’s guide listing is draft	Request an anonymous quote	Public-sale validation refuses the draft and identifies the store	test services-commerce:modules/pricing/tests/e2e/price-quote-public-sale.e2e.spec.js#refuses a draft product to an anonymous caller: 400 product_not_published, naming the store
`03`	The buyer’s Student term ends before the requested date and Alumni then qualifies	Request a staff quote for the later date	Dated qualification selects Member through Alumni rather than Student pricing	test services-commerce:modules/pricing/tests/e2e/price-quote-staff-form.e2e.spec.js#reads the student’s standing as of August 2027: the student term ended and the committed Alumni term holds, so Member prices, not Student

Edge Cases

Id	Given	When	Then	Provenance
`04`	The mug’s pricing function times out	Request its quote	The row price remains with an extension warning and cart-context indication	test services-commerce:modules/pricing/tests/e2e/price-quotes.e2e.spec.js#marks the mug as needing cart context and warns when its extension times out, the price unchanged

Planning

Implementation

Calculate and explain a buyer’s item price ​

Purpose ​

How It Works ​

Relationships ​