--- id: CAP-COM-CAT-001 title: Configure reusable sale-processing policies feature: FEAT-COM-CAT-01 product_area: commerce module: catalog revision: 1 status: draft product_intent: proposed implementation_evidence: observed supersedes: [] source_sha: services-commerce: c8b66a98e2490617aec38ba5c8165dd9bd0a8f9b react-console: baf6dae382d6f41dce976c7f848667ccc37e076f intent_sources: - 'services-commerce:docs/milestones/COMM-M1-set-up-what-you-sell.md#D9' - 'services-commerce:docs/milestones/plans/COMM-M1-plan.md#2. Scope (item 1)' - >- services-commerce:docs/milestones/plans/COMM-M1-plan.md#4. Assumptions (A1, A3) - >- services-commerce:docs/milestones/walkthroughs/COMM-M1-handoff.md#What changed after your review (1) purpose: >- Administrators define reusable payment and billing arrangements for the customer’s selling contexts. outcomes: - >- Each sale is processed under one known policy with a business unit and a currency that agree. - >- A policy in use is prevented from being removed or switched off from under the sales that depend on it. - >- A placed sale retains the rules it was placed under even when the policy later changes. concepts: - CON-COM-CAT-001 actors: - ACT-COM-001 - ACT-COM-004 surfaces: - console - api preconditions: - Accounting already provides the selected unit and supported currencies. postconditions: - >- The policy is retained at its next version and appears in Used By wherever Commerce points at it. permissions: - key: commerce.ordering-profiles.read where_checked: api scope: tenant - key: commerce.ordering-profiles.create where_checked: api scope: tenant - key: commerce.ordering-profiles.update where_checked: api scope: tenant - key: commerce.ordering-profiles.delete where_checked: api scope: tenant - key: commerce.ordering-profiles.bulk where_checked: api scope: tenant rules: - id: BR-CAP-COM-CAT-001-01 statement: >- Saving a checkout policy requires both the business unit receiving the sale and the currency used to price it. kind: validation enforced_at: - api - database - console must_prove: true provenance: test source: >- services-commerce:modules/configuration/tests/e2e/ordering-profiles.e2e.spec.js#answers 400 to a profile without a business unit or without a currency: the two money facts a profile always has origin: COMM-M1 plan A1 (docs/milestones/plans/COMM-M1-plan.md) - id: BR-CAP-COM-CAT-001-02 statement: >- Commerce refuses a policy currency outside the business unit’s supported currencies and preserves the previous record. kind: validation enforced_at: - service - console must_prove: true 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 origin: none - id: BR-CAP-COM-CAT-001-03 statement: >- The default merchant account must be active and match the policy’s unit and currency; an unknown account is refused, but an Accounting connection failure permits saving with a warning. kind: validation enforced_at: - service must_prove: true provenance: test source: >- services-commerce:modules/configuration/tests/unit/persistence/ordering-profile-merchant-account.spec.js#is let through, logged, when Accounting is unreachable origin: none examples: positive: An active USD account of an identical unit on a USD policy is accepted. negative: >- An inactive account, or a EUR account on a USD policy, fails validation identifying the field. - id: BR-CAP-COM-CAT-001-04 statement: >- Range-based card acceptance requires ordered minimum and maximum amounts, and the range is stored only with that acceptance mode. kind: validation enforced_at: - api - database - console must_prove: true 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) origin: none note: >- The recorded minimum-range recommendation remains pending Product confirmation. - id: BR-CAP-COM-CAT-001-05 statement: >- The pay-now window defaults to thirty minutes and accepts values from one minute through one week. kind: validation enforced_at: - database - console must_prove: true 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 origin: COMM-M1 plan A3 (docs/milestones/plans/COMM-M1-plan.md) - id: BR-CAP-COM-CAT-001-06 statement: >- Creating a minimally specified policy enables pay now, card and bank debit, store credit, a thirty-minute window, pro forma invoicing and unrestricted card acceptance, with no collection option or card fee. kind: policy enforced_at: - service - database must_prove: false provenance: test source: >- services-commerce:modules/configuration/tests/e2e/ordering-profiles.e2e.spec.js#gives every setting the request left out its default: pay now, the card and ACH system methods, store credit, no collection option, thirty minutes, pro forma, a card always, no fee origin: none - id: BR-CAP-COM-CAT-001-07 statement: >- Commerce identifies and refuses blank payment-method, collection-option and installment-plan entries, and refuses duplicate payment methods. kind: validation enforced_at: - api - service - console must_prove: true provenance: test source: >- services-commerce:modules/configuration/tests/unit/api/blank-ordering-profile-ids.spec.js#refuses a blank entry beside a good one on a create, naming the entry origin: none - id: BR-CAP-COM-CAT-001-08 statement: >- A policy keeps its supplied or name-derived identity permanently and rejects defaults, new and resolve as identities regardless of case. kind: validation enforced_at: - api - service must_prove: false 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 origin: none - id: BR-CAP-COM-CAT-001-09 statement: >- Once policies exist, one active policy remains the workspace default: creation selects the first, and staff can transfer the designation but cannot clear it. kind: invariant enforced_at: - service - database must_prove: true 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 origin: COMM-M1 plan A1 (docs/milestones/plans/COMM-M1-plan.md) - id: BR-CAP-COM-CAT-001-10 statement: >- Deactivating or deleting a policy serving as a workspace or application default is refused with the retaining default identified. kind: lifecycle enforced_at: - service - console must_prove: true 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) origin: none - id: BR-CAP-COM-CAT-001-11 statement: >- Store, checkout and order references prevent policy deletion, with a store reference identified in the applicable refusal. kind: lifecycle enforced_at: - service - database must_prove: true 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 origin: none - id: BR-CAP-COM-CAT-001-12 statement: >- Used By reports Commerce-held store and application-default references and the workspace-default designation, excluding references held by other applications. kind: policy enforced_at: - service - console must_prove: false provenance: test source: >- services-commerce:modules/configuration/tests/integration/services/persistence/ordering-profiles.queries.integration.spec.js#answers the tenant default’s stores by name, its flag and the pointers as one list origin: none - id: BR-CAP-COM-CAT-001-13 statement: >- Staff replace a complete policy using its read version; Commerce rejects a stale version without overwriting the saved policy. kind: invariant enforced_at: - api - service must_prove: true provenance: test source: >- services-commerce:modules/configuration/tests/e2e/ordering-profiles.e2e.spec.js#answers 409 to a stale version origin: none - id: BR-CAP-COM-CAT-001-14 statement: >- The order’s retained policy snapshot contains settlement, card, invoicing and fee-product settings independently of subsequent policy edits. kind: invariant enforced_at: - service must_prove: true 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 origin: none - id: BR-CAP-COM-CAT-001-15 statement: >- Policy reads require read permission and each creation, replacement or deletion requires its matching administrator permission; readers cannot change saved records. kind: permission enforced_at: - api - console must_prove: true provenance: test source: >- services-commerce:modules/configuration/tests/e2e/configuration-security.e2e.spec.js#is refused the replacements, 403 permission_missing, the records unchanged origin: none - id: BR-CAP-COM-CAT-001-16 statement: >- A full lock prevents replacing a checkout policy, and either full or deletion-only locking prevents removing it. kind: policy enforced_at: - service must_prove: true provenance: observed source: >- services-commerce:modules/configuration/services/persistence/ordering-profiles.ts origin: none scenarios: - id: SC-CAP-COM-CAT-001-01 given: No policy exists in the workspace when: Create Main using only its business unit and USD then: >- The first version of Main becomes default and receives the remaining default settings provenance: test source: >- services-commerce:modules/configuration/tests/e2e/ordering-profiles.e2e.spec.js#answers 200, the id its name suggests, in the tenant of the path, at version 1, the first profile the tenant default - id: SC-CAP-COM-CAT-001-02 given: Main carries the workspace-default designation when: Request removal of Main then: The refusal identifies its default role provenance: test source: >- services-commerce:modules/configuration/tests/e2e/ordering-profiles.e2e.spec.js#answers 409 profile_is_default for the tenant default, naming the rule - id: SC-CAP-COM-CAT-001-03 given: Card acceptance uses an amount range when: Submit that policy without the minimum then: Validation identifies the absent minimum and prevents saving 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) edge_cases: - id: SC-CAP-COM-CAT-001-04 given: The Accounting connection is unavailable when: Save a policy with a default merchant account then: Saving continues with a warning that eligibility was not verified provenance: test source: >- services-commerce:modules/configuration/tests/unit/persistence/ordering-profile-merchant-account.spec.js#is let through, logged, when Accounting is unreachable depends_on: [] related: - CAP-COM-CAT-002 - CAP-COM-CAT-003 journeys: - JNY-COM-CAT-001 open_questions: [] evidence: - >- Pinned service inputs: modules/configuration/aws/api/ordering-profiles.routes.ts and .schemas.ts; services/persistence/ordering-profiles.ts; db/ordering-profiles.table.ts; tests/e2e/ordering-profiles.e2e.spec.js, configuration-security.e2e.spec.js; tests/integration (persistence, table); tests/unit (rules, merchant account, blank ids, ranges) - >- Pinned console inputs: components/commerce/ordering-profiles/** (the Checkout Policies list, view and editor), lib/commerce/ordering-profiles/** and its tests, e2e/mock/commerce-checkout-policies.mock.spec.ts 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-DAT-001, TC-DAT-002, TC-DAT-003, TC-DAT-004, TC-LOG-004, TC-LOG-005, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-005, TC-PRV-001, TC-PRV-002] --- # Configure reusable sale-processing policies ## Purpose Administrators define reusable payment and billing arrangements for the customer’s selling contexts. ## How It Works An administrator starts from Checkout Policies and chooses the financial context for a new policy. The editor collects payment, card and invoicing choices around that context. Saving returns the policy for inspection and the view summarizes how buyers pay. Used By helps staff understand the dependencies they must consider before changing availability or removing the record. Validation failures identify unsuitable choices, and version conflicts require staff to revisit the saved record. Orders use retained policy settings so maintenance has a different effect from altering a placed sale. The product should explicitly settle whether unavailable Accounting validation permits an unchecked account. ## Relationships The select the policy governing a sale capability supplies related configuration or assessment used in this work. The configure a store’s offered assortment capability supplies related configuration or assessment used in this work.