--- id: SVC-COM-CAT-pricing title: 'Pricing: audiences, schedules, purchasing settings, pricing functions and the price engine' product_area: commerce module: catalog repository: services-commerce source_module: modules/pricing revision: 1 status: draft design_intent: proposed implementation_evidence: observed inference: [] source_sha: services-commerce: c8b66a98e2490617aec38ba5c8165dd9bd0a8f9b react-console: baf6dae382d6f41dce976c7f848667ccc37e076f owns: - DOM-COM-CAT-004 does_not_own: - 'MOD-ACC-PRD and MOD-ACC-BKS supply financial prices, exchange rates and legacy pricing inputs.' - MOD-PFM-ELG defines and evaluates eligibility. - MOD-MBR-MEM supplies membership qualification data. - MOD-PFM-INT maintains the extension registry. - MOD-ACC-TRX performs tax calculation. - MOD-COM-ORD controls checkout and placement. operations: - operation_id: createPricingAudience intent: Prepare a new pricing audience with validated configuration. access: console permission: commerce.pricing-audiences.create realises: - CAP-COM-CAT-010 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: listPricingAudiences intent: Browse the workspace’s pricing audiences using supported filters. access: console permission: commerce.pricing-audiences.read realises: - CAP-COM-CAT-010 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: getPricingAudience intent: Inspect the selected pricing audience and its retained details. access: console permission: commerce.pricing-audiences.read realises: - CAP-COM-CAT-010 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: updatePricingAudience intent: Save permitted changes to the selected pricing audience at its read version. access: console permission: commerce.pricing-audiences.update realises: - CAP-COM-CAT-010 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: deletePricingAudience intent: Remove the selected pricing audience when protection and dependencies permit. access: console permission: commerce.pricing-audiences.delete realises: - CAP-COM-CAT-010 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: createPricingSchedule intent: Prepare a new price schedule with validated configuration. access: console permission: commerce.pricing-schedules.create realises: - CAP-COM-CAT-011 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: listPricingSchedules intent: Browse the workspace’s price schedules using supported filters. access: console permission: commerce.pricing-schedules.read realises: - CAP-COM-CAT-011 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: getPricingSchedule intent: Inspect the selected price schedule and its retained details. access: console permission: commerce.pricing-schedules.read realises: - CAP-COM-CAT-011 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: updatePricingSchedule intent: Save permitted changes to the selected price schedule at its read version. access: console permission: commerce.pricing-schedules.update realises: - CAP-COM-CAT-011 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: deletePricingSchedule intent: Remove the selected price schedule when protection and dependencies permit. access: console permission: commerce.pricing-schedules.delete realises: - CAP-COM-CAT-011 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: getProductPurchasingSettings intent: Inspect saved product purchasing choices or their defaults. access: console permission: commerce.product-purchasing-settings.read realises: - CAP-COM-CAT-012 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: setProductPurchasingSettings intent: Replace the complete purchasing choices for a product. access: console permission: commerce.product-purchasing-settings.update realises: - CAP-COM-CAT-012 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: getProductExtension intent: Inspect the product handler reference for the selected extension point. access: console permission: commerce.product-extensions.read realises: - CAP-COM-CAT-012 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: setProductExtension intent: Save the product’s registered-handler reference at its read version. access: console permission: commerce.product-extensions.update realises: - CAP-COM-CAT-012 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: deleteProductExtension intent: Remove the selected product handler reference. access: console permission: commerce.product-extensions.delete realises: - CAP-COM-CAT-012 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: createPriceQuote intent: Calculate and explain item amounts for an authorized signed-in or staff request. access: portal permission: commerce.price-quotes.read realises: - CAP-COM-CAT-013 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: createPublicPriceQuote intent: Calculate visitor amounts without reading a named person or checkout. access: public permission: none (anonymous) realises: - CAP-COM-CAT-013 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: pricing.priceCheckout intent: Calculate checkout lines through the common deterministic price engine. access: internal permission: none (in-process) realises: - CAP-COM-CAT-013 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: pricing.prepareAudienceSettlement intent: Prepare qualification rechecks and settle audiences within placement. access: internal permission: none (in-process) realises: - CAP-COM-CAT-013 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: pricing.quoteTax intent: Calculate tax for the requested lines and address through the selected provider. access: internal permission: none (in-process) realises: - CAP-COM-CAT-004 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: pricing.seedBuiltInPricingAudiences intent: Create absent Standard and Member audiences during workspace setup. access: internal permission: none (provisioning) realises: - CAP-COM-CAT-010 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: pricing.realizePricingAudienceHandovers intent: Translate pending special-price handovers into scoped audiences when a caller supplies binding ports. access: internal permission: none (no caller) realises: - CAP-COM-CAT-010 published_to_submissions: 'not published: this operation has no registered Submissions binding' events: [] jobs: - Special-price handover realization is implemented as a callable function but has no deployed invoker. integrations: - system: Accounting catalog tables direction: outbound contract: >- Workspace-scoped reads obtain Accounting products, currencies, rows and bulk rules; realization writes only its allowed completion stamp. - system: Platform eligibility direction: outbound contract: >- Environment-selected display transport calls Platform where configured; placement uses the database eligibility recheck. - system: Membership facts direction: outbound contract: The membership facts port currently supplies fixture data. - system: Extension SDK direction: outbound contract: >- Stored handler references feed the preprocessing, product-calculation and order-review SDK using fixture factories. - system: Accounting tax module direction: outbound contract: >- The selected Accounting provider calls tax calculation; otherwise the interim zone-table provider is used. consistency: - rule: 'Quote results are not persisted or binding, and placement computes charged amounts again.' kind: transactional compensation: There is no reserved quote amount to restore. - rule: Placement rechecks relevant audience bindings and stamps first sales within the order transaction. kind: transactional compensation: Lapsed qualification rejects placement and rolls back its stamps. - rule: >- Commit checks require adjacent intervals; used names and starts are protected, current ends have a bounded exception and elapsed periods reject edits. kind: transactional compensation: A refused interval change rolls back the schedule save. - rule: >- Schedule disabling and purchasing selection coordinate through exclusive and shared locks on the same row. kind: transactional compensation: The conflicting request receives the applicable in-use or inactive refusal. - rule: >- The realization function can bind and activate migrated special-price audiences, but no runtime caller invokes it. kind: eventual compensation: Pending handovers remain until a caller and real binding adapter are supplied. evidence: - >- services-commerce at c8b66a98: modules/pricing/aws/api/*.routes.ts, services/**/*.ts, db/*.table.ts, extensions/*.ts, contracts/extensions.ts; aws/commerce.service-calls.ts. - 'react-console at baf6dae3: lib/commerce/pricing/live.ts, lib/commerce/audiences/live.ts.' controls: [TC-IAM-001, TC-IAM-002, TC-IAM-004, TC-IAM-005, TC-IAM-006, 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-CRY-002, TC-CRY-003, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-LOG-004, TC-LOG-005, TC-CHG-001, TC-CHG-002, TC-CHG-003, TC-CHG-004, TC-CHG-007, TC-AVL-002, TC-AVL-003, TC-AVL-004, TC-AVL-005, TC-MON-001, TC-MON-002, TC-MON-003, TC-MON-004, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-004, TC-PI-005, TC-PRV-001, TC-PRV-002] --- # Pricing: audiences, schedules, purchasing settings, pricing functions and the price engine ## What This Service Is For Pricing provides one deterministic amount calculation shared by quote, checkout and placement. Its configuration describes qualifying audiences, dated intervals and product purchasing choices. ## Boundary Accounting owns price rows, exchange rates and migrated handovers. Platform supplies eligibility and extension seams; Membership owns qualification facts. Orders owns the checkout and placement transaction. ## Operations in Words Staff maintain audiences and retained schedule APIs, replace purchasing settings and assign product handlers. Signed and public quote routes return amounts with their explanations. Internal seams price checkout, settle eligibility and seed built-ins. The available handover function remains without a runtime caller. ## Events and Jobs Pricing publishes no external event and has no deployed background realization job. Handover realization is an available function with tests, not scheduled production work. ## Consistency Guarantees Placement recalculates amounts and checks applicable eligibility inside its transaction. Interval adjacency and protection are enforced at commit and write time. Membership facts and handler factories remain fixtures; display eligibility transport depends on environment configuration.