--- id: CAP-COM-CAT-011 title: Maintain dated pricing periods feature: FEAT-COM-CAT-03 product_area: commerce module: catalog revision: 1 status: draft product_intent: proposed implementation_evidence: inconsistent source_sha: services-commerce: c8b66a98e2490617aec38ba5c8165dd9bd0a8f9b react-console: baf6dae382d6f41dce976c7f848667ccc37e076f intent_sources: - 'services-commerce:docs/milestones/COMM-M1-set-up-what-you-sell.md#D2' - 'services-commerce:docs/milestones/COMM-M1-set-up-what-you-sell.md#D6' - 'services-commerce:docs/milestones/COMM-M1-set-up-what-you-sell.md#D4-F1' - 'services-commerce:docs/debt/pricing-schedules-owned-by-event.md' purpose: >- Administrators and future owning applications coordinate product price changes across dated periods. outcomes: - A price edits exactly at a period boundary. - Each past charge stays explainable by the period that priced it. concepts: - CON-COM-CAT-004 actors: - ACT-COM-001 - ACT-COM-007 surfaces: - api permissions: - key: commerce.pricing-schedules.read where_checked: api scope: tenant - key: commerce.pricing-schedules.create where_checked: api scope: tenant - key: commerce.pricing-schedules.update where_checked: api scope: tenant - key: commerce.pricing-schedules.delete where_checked: api scope: tenant - key: commerce.pricing-schedules.bulk where_checked: api scope: tenant rules: - id: BR-CAP-COM-CAT-011-01 statement: >- The implemented price schedule holds workspace periods without ownership and rejects an owner such as an event in its request. kind: policy enforced_at: - api - database must_prove: true provenance: test source: >- services-commerce:modules/pricing/tests/e2e/pricing-schedules.e2e.spec.js#answers 400 to an event owner (a schedule has none, COMM-M1 D2), to a property outside the contract and to a tenant_id other than the path’s origin: COMM-M1 D2 (docs/milestones/COMM-M1-set-up-what-you-sell.md) note: >- Product’s later ownership ruling assigns schedules to their events, while implementation of that ownership remains deferred. - id: BR-CAP-COM-CAT-011-02 statement: >- A period includes its start boundary and excludes its end in the schedule’s time zone. kind: calculation enforced_at: - service - database must_prove: true provenance: test source: >- services-commerce:modules/pricing/tests/integration/services/persistence/pricing-schedules.queries.integration.spec.js#finds the period containing an instant: the open start, a boundary belonging to the period it starts, the open end origin: COMM-M1 D6 (docs/milestones/COMM-M1-set-up-what-you-sell.md) - id: BR-CAP-COM-CAT-011-03 statement: >- Adjacent periods share boundaries without gaps or overlaps, with an open start permitted only first and an open end only last. kind: invariant enforced_at: - service - database must_prove: true provenance: test source: >- services-commerce:modules/pricing/tests/integration/db/member-pricing-tables.table.integration.spec.js#refuses an overlap, a second open end and an open start that is not first origin: COMM-M1 D6 (docs/milestones/COMM-M1-set-up-what-you-sell.md) - id: BR-CAP-COM-CAT-011-04 statement: >- Elapsed or used periods retain their names and boundaries and prevent their own and their schedule’s deletion, except for the permitted current-end adjustment; the first-sale marker is permanent. kind: invariant enforced_at: - service - database must_prove: true provenance: test source: >- services-commerce:modules/pricing/tests/integration/db/member-pricing-tables.table.integration.spec.js#records the first sale once, never cleared or moved, after which the period keeps its name and is never deleted, nor its schedule origin: COMM-M1 D6 (docs/milestones/COMM-M1-set-up-what-you-sell.md) - id: BR-CAP-COM-CAT-011-05 statement: >- Staff may adjust a current period’s end no earlier than now, shifting the next period’s start with it even after a sale, while preserving prior charges. kind: lifecycle enforced_at: - service - database must_prove: true provenance: test source: >- services-commerce:modules/pricing/tests/e2e/pricing-schedules.e2e.spec.js#extends the sold-in Early Bird by a week, Regular starting where it now ends, its first sale untouched origin: COMM-M1 D6 (docs/milestones/COMM-M1-set-up-what-you-sell.md) - id: BR-CAP-COM-CAT-011-06 statement: >- A period identity belongs to one workspace schedule, and reuse by another schedule is refused with the identity identified. kind: validation enforced_at: - service - database must_prove: true provenance: test source: >- services-commerce:modules/pricing/tests/e2e/pricing-schedules.e2e.spec.js#answers 400 with the problem code period_id_taken, naming the id, to a second schedule taking a period id, creating nothing origin: none - id: BR-CAP-COM-CAT-011-07 statement: >- Referenced schedules cannot be deactivated or deleted, with product counts and up to five product references reported; inactive schedules cannot be selected by products. kind: lifecycle enforced_at: - service - database must_prove: true provenance: test source: >- services-commerce:modules/pricing/tests/integration/services/persistence/pricing-schedules.integration.spec.js#refuses with schedule_in_use, the count in the sentence, and the count and the first five product ids in the details origin: COMM-M1 D4-F1 (docs/milestones/COMM-M1-set-up-what-you-sell.md) - id: BR-CAP-COM-CAT-011-08 statement: >- A versioned schedule replacement retains unchanged periods, updates permitted changes, inserts additions and removes omitted periods where allowed. kind: invariant enforced_at: - service must_prove: true provenance: test source: >- services-commerce:modules/pricing/tests/integration/services/persistence/pricing-schedules.integration.spec.js#answers the replaced record at version 2: the kept period at version 1, the changed one at version 2, the new one inserted, the one left out gone origin: none - id: BR-CAP-COM-CAT-011-09 statement: >- Staff see a product’s schedule periods as pricing-grid columns, without a standalone schedules screen. kind: policy enforced_at: - console must_prove: false provenance: documented source: 'services-commerce:docs/debt/pricing-schedules-owned-by-event.md' origin: >- COMM-M1 walkthrough ruling R5 (docs/debt/pricing-schedules-owned-by-event.md) - id: BR-CAP-COM-CAT-011-10 statement: >- Schedule inspection requires read permission and schedule writes require administrator permissions. kind: permission enforced_at: - api must_prove: true provenance: test source: >- services-commerce:modules/pricing/tests/e2e/pricing-configuration-security.e2e.spec.js#lists and reads the audiences and the schedules origin: none - id: BR-CAP-COM-CAT-011-11 statement: >- A full lock prevents replacing a schedule, and either full or deletion-only locking prevents removing it. kind: policy enforced_at: - service must_prove: true provenance: observed source: >- services-commerce:modules/pricing/services/persistence/pricing-schedules.ts origin: none scenarios: - id: SC-CAP-COM-CAT-011-01 given: Early Bird’s end is the following period’s start when: Calculate just before and exactly at that boundary then: The earlier instant selects Early Bird and the boundary selects Regular provenance: documented source: >- services-commerce:docs/milestones/plans/COMM-M1-plan.md#D6. The price-period rules - id: SC-CAP-COM-CAT-011-02 given: Current Early Bird already has a first-sale marker when: Extend its end by one week then: >- Regular’s start moves with it and the earlier sale remains associated with Early Bird provenance: test source: >- services-commerce:modules/pricing/tests/e2e/pricing-schedules.e2e.spec.js#still reads a sale made before the change in the same period, and now a day after the old end in Early Bird too depends_on: [] related: - CAP-COM-CAT-012 - CAP-COM-CAT-013 journeys: - JNY-COM-CAT-002 open_questions: - OQ-COM-CAT-001 evidence: - >- Pinned service inputs: modules/pricing/aws/api/pricing-schedules.routes.ts and .schemas.ts; services/persistence/pricing-schedules.ts; db/pricing-schedules.table.ts, pricing-periods.table.ts; tests (schedules e2e, persistence, queries, table); docs/debt/pricing-schedules-owned-by-event.md - >- Pinned console inputs: components/commerce/pricing-schedules/** (unreferenced since the ruling), lib/commerce/pricing-schedules/** and tests controls: [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-CRY-004, TC-DAT-004, TC-LOG-004, TC-AVL-004, TC-MON-001, TC-MON-002, TC-MON-004, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-004, TC-PI-005] --- # Maintain dated pricing periods ## Purpose Administrators and future owning applications coordinate product price changes across dated periods. ## How It Works A schedule organizes named periods with a time zone. Products following it expose those periods in the grid. Saving a schedule reconciles retained, edited, added and omitted periods against its version. Historical use and elapsed time constrain what can change. Permitted current-end edits coordinate the next period without rewriting earlier charges. The implemented API still accepts ownerless schedules after the standalone console editor was removed. The product should settle the owner transition before adding schedule creation to a future design. ## Relationships The configure product purchasing and price adjustments capability supplies related configuration or assessment used in this work. The calculate and explain a buyer’s item price capability supplies related configuration or assessment used in this work.