--- id: DOM-COM-CAT-001 title: Checkout Policy realises: CON-COM-CAT-001 product_area: commerce module: catalog revision: 1 status: draft design_intent: proposed implementation_evidence: observed source_sha: services-commerce: c8b66a98e2490617aec38ba5c8165dd9bd0a8f9b react-console: baf6dae382d6f41dce976c7f848667ccc37e076f owned_by: SVC-COM-CAT-configuration readable_by: - SVC-COM-CAT-catalog - SVC-COM-CAT-pricing - SVC-COM-CAT-promotions lifecycle: STATE-COM-CAT-001 custom_fields: none identity: >- Staff choose a permanent readable policy key, or creation derives it from the name. Reserved routing words cannot be keys. Workspace and application defaults refer to policies rather than creating separate policy identities. attributes: - name: name and description kind: text required: true computed: false notes: A nonblank name labels the policy; staff may also supply a description. - name: active kind: enum required: true computed: false notes: >- Active policies support new checkout contexts. Existing orders retain their captured settings after deactivation. - name: business unit kind: reference required: true computed: false notes: The referenced Accounting unit receives every sale line. - name: currency kind: reference required: true computed: false notes: The sale uses one currency supported by its Accounting unit. - name: default merchant and bank accounts kind: reference required: false computed: false notes: Optional defaults select settlement accounts when a tender supplies no account. - name: settlement rules kind: collection required: true computed: false notes: >- These settings combine acceptance requirements, ordered tender choices, credit and collection options, payment timing and saved or split payments. - name: card acceptance and card fee kind: enum required: true computed: false notes: >- Card use is unrestricted, disallowed or limited to a total range; range mode needs both bounds. A separate choice governs card fees. - name: invoicing rules kind: collection required: false computed: false notes: >- Optional Accounting references select invoice terms, batch and template, together with the pro forma choice. - name: fee products kind: collection required: false computed: false notes: >- Referenced products represent cancellation, restocking, order, label, discount, tax and shipping charges. - name: installment choice kind: collection required: false computed: false notes: The policy can list installment plans and control whether buyers choose among them. - name: checkout instructions kind: text required: false computed: false notes: Optional instructions appear during checkout. - name: extension points for non-store contexts kind: reference required: false computed: false notes: >- Outside a store, these references select preprocessing and order-price handlers. Store-specific references take precedence in a store. - name: post-purchase policy kind: collection required: false computed: false notes: Orders applies the retained cancellation and amendment choices after a sale. - name: workspace default designation kind: enum required: true computed: false notes: >- The first policy establishes an active workspace default; staff transfer that designation to another active policy. - name: application defaults kind: collection required: false computed: false notes: The defaults document replaces the application-to-policy map together with the workspace selection. - name: used by kind: computed required: false computed: true notes: >- This read summarizes Commerce-held store and default references; references held by other applications are outside its coverage. - name: tax zones and rates kind: collection required: false computed: false notes: >- Interim zones contain country, optional region and postal prefix, plus ordered rate entries with optional type and date restrictions. - name: protection and version kind: computed required: true computed: true notes: Replacements use the read version. System metadata records protection and the creator and latest editor. relationships: - to: DOM-COM-CAT-002 cardinality: one policy to many stores ownership: Stores retain the policy reference and prevent its removal while they use it. cross_service: false - to: DOM-COM-CAT-004 cardinality: one policy to every price of a sale ownership: Pricing obtains the sale currency from the policy without storing prices on it. cross_service: false - to: DOM-COM-CAT-005 cardinality: informational ownership: Sample promotion assessment uses the selected policy’s unit and currency. cross_service: false invariants: - id: INV-DOM-COM-CAT-001-01 statement: The save requires an Accounting unit and one of that unit’s currencies. enforced_at: - api - service provenance: test source: >- services-commerce:modules/configuration/tests/e2e/ordering-profiles.e2e.spec.js#answers 400 currency_not_supported_by_business_unit to a currency the business unit does not transact in - id: INV-DOM-COM-CAT-001-02 statement: 'After the first policy is created through the service, the workspace retains one active default policy.' enforced_at: - service - database provenance: test source: >- services-commerce:modules/configuration/tests/integration/services/persistence/ordering-profiles.integration.spec.js#makes a second profile no default, and one stating is_tenant_default the default in place of the first, in one transaction - id: INV-DOM-COM-CAT-001-03 statement: Policies referenced by workspace or application defaults cannot be deactivated or removed. enforced_at: - service provenance: test source: >- services-commerce:modules/configuration/tests/integration/services/persistence/ordering-profiles.integration.spec.js#refuses making an application default inactive, 409 profile_is_default naming the application, and deactivates it once no default names it (D31) - id: INV-DOM-COM-CAT-001-04 statement: Saving defaults requires active policies belonging to the same workspace. enforced_at: - service provenance: test source: >- services-commerce:modules/configuration/tests/e2e/ordering-profiles.e2e.spec.js#refuses a document naming an inactive or an unknown profile, 400, the document unchanged - id: INV-DOM-COM-CAT-001-05 statement: 'Retained store, checkout, order and default references block policy removal.' enforced_at: - database provenance: test source: >- services-commerce:modules/configuration/tests/e2e/ordering-profiles.e2e.spec.js#answers 409 naming the store while a store sells under the profile, then 200 once the store is gone - id: INV-DOM-COM-CAT-001-06 statement: 'A policy keeps its original key, and reserved keys are rejected.' enforced_at: - api - service - database provenance: test source: >- services-commerce:modules/configuration/tests/unit/persistence/ordering-profile-rules.spec.js#refuses a reserved id whatever its case and surrounding spaces - id: INV-DOM-COM-CAT-001-07 statement: Card-range mode requires ordered bounds; other card modes retain no bounds. enforced_at: - api - database provenance: test source: >- services-commerce:modules/configuration/tests/e2e/ordering-profiles.e2e.spec.js#answers 400 to a within_range acceptance without its minimum, naming card_minimum_total_minor, with or without the maximum (0755) - id: INV-DOM-COM-CAT-001-08 statement: Payment timing accepts a window of one minute through seven days. enforced_at: - database provenance: test source: >- services-commerce:modules/configuration/tests/integration/db/configuration-records.table.integration.spec.js#refuses a tender window outside one minute to a week, by ordering_profiles_tender_window_minutes_check - id: INV-DOM-COM-CAT-001-09 statement: >- Placed orders retain a snapshot of their settlement, card, invoice and fee-product settings despite later policy changes. enforced_at: - service provenance: test source: >- services-commerce:modules/configuration/tests/integration/services/persistence/ordering-profiles.queries.integration.spec.js#snapshotOf freezes the settlement, card, invoicing, fee-product and quote rules an order carries (22 §9), nothing else - id: INV-DOM-COM-CAT-001-10 statement: 'Zone writes include their rate entries, and rates use integer basis points within the supported limit.' enforced_at: - api - service - database provenance: test source: >- services-commerce:modules/configuration/tests/e2e/tax-zones.e2e.spec.js#deletes a zone with its rates, after which it reads 404; deleting it again is 404 physical: - ordering_profiles - ordering_profile_defaults - tax_zones - tax_rates evidence: - >- services-commerce at c8b66a98: modules/configuration/db/ordering-profiles.table.ts, ordering-profile-defaults.table.ts, tax-zones.table.ts, tax-rates.table.ts; services/persistence/ordering-profiles.ts (resolveOrderingProfile, snapshotOf, getOrderingProfileUsage), tax-zones.ts (listActiveTaxZones); docs/decisions/ordering-profiles.md. - >- services-commerce at c8b66a98: modules/configuration/tests/e2e/ordering-profiles.e2e.spec.js, tax-zones.e2e.spec.js; tests/integration/services/persistence/ordering-profiles.integration.spec.js. - >- react-console at baf6dae3: components/commerce/ordering-profiles/**, lib/commerce/ordering-profiles/live.ts. --- # Checkout Policy ## What It Models A checkout policy brings together the financial and processing choices for a sale. It supplies the Accounting unit, currency, tender arrangements, invoicing choices and products used for additional charges. Defaults provide fallback policy selection. Interim tax zones remain a facet of this concept while their ownership is unresolved. ## Identity and Attributes Each policy has a stable readable key. Financial references point to Accounting records and are checked when the policy is saved. Creation supplies defaults for omitted settings; replacement sends the complete record with its read version. ## Relationships Stores each select a policy, while checkouts and orders retain their own references. Pricing and promotion previews use its financial context. Existing references can prevent removal. ## Invariants Default policies must remain active. Orders preserve the relevant processing settings at placement, so later configuration edits do not alter that snapshot. Currency support is validated by the service rather than a database relationship to Accounting. ## How It Is Stored and Shared Configuration owns policies, defaults and interim tax zones. Other Commerce modules read them in process. Accounting remains responsible for the referenced financial records. These records have no declared custom-field capability, historical change feed or published change events. ## Open Design Questions An Accounting connection failure permits an unchecked merchant-account save and logs the warning without displaying it. Tax ownership and authority to set or remove protection still need product decisions.