--- id: CAP-COM-CAT-013 title: Calculate and explain a buyer’s item price feature: FEAT-COM-CAT-03 product_area: commerce module: catalog revision: 1 status: draft product_intent: proposed implementation_evidence: observed source_sha: services-commerce: c8b66a98e2490617aec38ba5c8165dd9bd0a8f9b react-console: baf6dae382d6f41dce976c7f848667ccc37e076f intent_sources: - 'services-commerce:docs/milestones/COMM-M1-set-up-what-you-sell.md#D5' - 'services-commerce:docs/milestones/COMM-M1-set-up-what-you-sell.md#D8' - 'services-commerce:docs/milestones/COMM-M1-set-up-what-you-sell.md#D10' - 'services-commerce:docs/milestones/COMM-M1-set-up-what-you-sell.md#D14' - 'services-commerce:docs/milestones/COMM-M1-set-up-what-you-sell.md#D5-F1' - 'services-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) purpose: >- Commerce calculates the price appropriate to an item, subject, currency and selling context. 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. concepts: - CON-COM-CAT-004 actors: - ACT-COM-003 - ACT-COM-005 - ACT-COM-006 - ACT-COM-007 surfaces: - console - portal - api permissions: - key: commerce.price-quotes.read where_checked: api scope: tenant - key: commerce.orders.create where_checked: service scope: tenant rules: - id: BR-CAP-COM-CAT-013-01 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] statement: >- 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. kind: calculation enforced_at: - service must_prove: true provenance: test source: >- 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 origin: COMM-M1 D5 (docs/milestones/COMM-M1-set-up-what-you-sell.md) - id: BR-CAP-COM-CAT-013-02 proved_by: [ATS-COM-CAT-010-10, ATS-COM-CAT-013-02, ATS-COM-CAT-013-16, TST-COM-CAT-085] statement: >- Standard always qualifies, and active eligibility audiences qualify only on an eligible decision for the qualification date; other verdicts retain their reasons without qualification. kind: calculation enforced_at: - service must_prove: true provenance: test source: >- 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 origin: none - id: BR-CAP-COM-CAT-013-03 proved_by: [ATS-COM-CAT-011-11, ATS-COM-CAT-013-03, ATS-COM-CAT-013-17, TST-COM-CAT-086] statement: >- A missing audience-period price falls back to that audience’s Always price and then another qualifying audience, ultimately Standard. kind: calculation enforced_at: - service - console must_prove: true provenance: test source: >- 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 origin: COMM-M1 D6 (docs/milestones/COMM-M1-set-up-what-you-sell.md) - id: BR-CAP-COM-CAT-013-04 proved_by: [ATS-COM-CAT-013-04, TST-COM-CAT-084] statement: >- Each pricing rounding step uses whole minor currency units and moves exact halves away from zero. kind: calculation enforced_at: - service - console must_prove: true provenance: test source: >- services-commerce:modules/pricing/tests/unit/engine/rounding.spec.js#rounds a negative half down, away from zero, where Math.round would answer -2 origin: COMM-M1 D5 (docs/milestones/COMM-M1-set-up-what-you-sell.md) - id: BR-CAP-COM-CAT-013-05 proved_by: [ATS-COM-CAT-013-05, TST-COM-CAT-086] statement: >- 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. kind: calculation enforced_at: - service must_prove: true provenance: test source: >- 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 origin: COMM-M1 plan A14 (MP D-19) (docs/milestones/plans/COMM-M1-plan.md) - id: BR-CAP-COM-CAT-013-06 proved_by: [ATS-COM-CAT-013-05, TST-COM-CAT-086] statement: >- Standard currency prohibition prevents purchase by every audience in that currency, and products outside their sale windows cannot be priced for purchase. kind: validation enforced_at: - service must_prove: true provenance: test source: >- 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) origin: none - id: BR-CAP-COM-CAT-013-07 proved_by: [ATS-COM-CAT-006-15, ATS-COM-CAT-013-06, TST-COM-CAT-057] statement: >- Public buyers cannot quote drafts, products without listings or products outside the store assortment; console staff with order-create permission receive the exemption. kind: policy enforced_at: - service must_prove: true provenance: test source: >- 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 origin: COMM-M1 D8 (docs/milestones/COMM-M1-set-up-what-you-sell.md) - id: BR-CAP-COM-CAT-013-08 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] statement: >- Anonymous quotes require a store, exclude person and cart references, and return Standard and publicly displayed audience prices with the sign-in notice. kind: policy enforced_at: - api - service must_prove: true provenance: test source: >- 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 origin: COMM-M1 D10 (docs/milestones/COMM-M1-set-up-what-you-sell.md) - id: BR-CAP-COM-CAT-013-09 proved_by: [ATS-COM-CAT-013-08, TST-COM-CAT-068, TST-COM-CAT-087] statement: >- Required extension failure prevents placement and records an exception; optional placement failures and quote failures skip the extension with a warning. kind: policy enforced_at: - service must_prove: true provenance: test source: >- 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) origin: COMM-M1 D14 (docs/milestones/COMM-M1-set-up-what-you-sell.md) - id: BR-CAP-COM-CAT-013-10 proved_by: [ATS-COM-CAT-013-09] statement: >- An order-pricing extension fee is refused during preview and placement while invoicing support remains unavailable, without saving the sale. kind: policy enforced_at: - service must_prove: true provenance: documented source: 'services-commerce:docs/milestones/COMM-M1-set-up-what-you-sell.md#D5-F1' origin: COMM-M1 D5-F1 (docs/milestones/COMM-M1-set-up-what-you-sell.md) - id: BR-CAP-COM-CAT-013-11 proved_by: [ATS-COM-CAT-013-10, TST-COM-CAT-058] statement: >- Staff may preview hypothetical audiences or dates with assumptions identified in the response, while portal buyers cannot use those overrides. kind: permission enforced_at: - api - service must_prove: true provenance: test source: >- services-commerce:modules/pricing/tests/e2e/price-quote-staff-form.e2e.spec.js#refuses a portal member either property, 403, and prices them without origin: none - id: BR-CAP-COM-CAT-013-12 proved_by: [ATS-COM-CAT-013-11, TST-COM-CAT-060] statement: >- 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. kind: permission enforced_at: - service must_prove: true provenance: test source: >- 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 origin: none - id: BR-CAP-COM-CAT-013-13 proved_by: [ATS-COM-CAT-013-12, TST-COM-CAT-060, TST-COM-CAT-083] statement: >- Quoting creates no records or price commitment, and placement recomputes the payable price. kind: invariant enforced_at: - service must_prove: true provenance: test source: >- services-commerce:modules/pricing/tests/unit/engine/quote-tolerance.spec.js#differs with the changes when a price moved, never answering the previewed price origin: >- COMM-M1 plan A13 (order domain D13) (docs/milestones/plans/COMM-M1-plan.md) - id: BR-CAP-COM-CAT-013-14 proved_by: [ATS-COM-CAT-011-11, ATS-COM-CAT-013-13, ATS-COM-CAT-013-17, TST-COM-CAT-081] statement: >- Placement rechecks eligibility-audience lines in the order transaction, rejects lapsed qualification per line and marks each period’s first sale once. kind: policy enforced_at: - service must_prove: true provenance: test source: >- 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 origin: none - id: BR-CAP-COM-CAT-013-15 proved_by: [ATS-COM-CAT-013-14, TST-COM-CAT-059, TST-COM-CAT-060] statement: >- Quote requests accept at most fifty items with positive integer quantities and require quote-read permission, included in every built-in role. kind: validation enforced_at: - api must_prove: true provenance: test source: >- services-commerce:modules/pricing/tests/e2e/price-quotes.e2e.spec.js#refuses more than fifty items origin: none scenarios: - id: SC-CAP-COM-CAT-013-01 given: The guide has Standard and Member price rows when: Quote for a qualified member then: The response uses the eighty-dollar Member price provenance: documented source: >- services-commerce:docs/milestones/plans/COMM-M1-plan.md#D5. The order of the price calculation - id: SC-CAP-COM-CAT-013-02 given: The store’s guide listing is draft when: Request an anonymous quote then: Public-sale validation refuses the draft and identifies the store provenance: test source: >- 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 - id: SC-CAP-COM-CAT-013-03 given: >- The buyer’s Student term ends before the requested date and Alumni then qualifies when: Request a staff quote for the later date then: >- Dated qualification selects Member through Alumni rather than Student pricing provenance: test source: >- 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: SC-CAP-COM-CAT-013-04 given: The mug’s pricing function times out when: Request its quote then: >- The row price remains with an extension warning and cart-context indication provenance: test source: >- 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 depends_on: - CAP-COM-CAT-010 - CAP-COM-CAT-011 - CAP-COM-CAT-012 related: - CAP-COM-CAT-008 - CAP-COM-CAT-016 journeys: - JNY-COM-CAT-002 - JNY-COM-CAT-003 - JNY-COM-CAT-005 evidence: - >- Pinned service inputs: modules/pricing/aws/api/price-quotes.routes.ts and .schemas.ts; services/engine/** (steps 1 to 9), services/inputs/**, services/quotes/**, services/eligibility/**, services/extensions/**, services/placement/**, extensions/**; tests (quote e2e, member pricing scenarios, engine, extensions, eligibility, placement) - >- Pinned console inputs: components/commerce/pricing/preview-as-bar.tsx and lib/commerce/pricing/** (Preview As), components/order-composer/priced-preview.tsx (the staff order composer’s priced preview, owned by the orders module) 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-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] exercised_by: [FAS-COM-CAT-03-01, FAS-COM-CAT-03-02, FAS-COM-CAT-03-03, FAS-COM-CAT-03-04, FAS-COM-CAT-03-05] suites: [TST-COM-CAT-056, TST-COM-CAT-057, TST-COM-CAT-058, TST-COM-CAT-059, TST-COM-CAT-060, TST-COM-CAT-068, TST-COM-CAT-081, TST-COM-CAT-082, TST-COM-CAT-083, TST-COM-CAT-084, TST-COM-CAT-085, TST-COM-CAT-086, TST-COM-CAT-087] --- # 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.