--- id: CAP-COM-ORD-017 title: Arrange vendor stock purchases feature: FEAT-COM-ORD-07 product_area: commerce module: orders revision: 1 status: draft product_intent: proposed implementation_evidence: observed supersedes: - CAP-COM-INV-019 - CAP-COM-INV-020 source_sha: services-commerce: c8b66a98e2490617aec38ba5c8165dd9bd0a8f9b react-console: baf6dae382d6f41dce976c7f848667ccc37e076f intent_sources: - >- services-commerce:docs/migrations/purchasing/README.md#D-P8P-16. A supplier's country is one of ISO 3166-1 alpha-2's assigned codes (Q07, Andrew 2026-10-19) purpose: Purchasing staff record supplier commitments and monitor stock that remains due. outcomes: - Purchasing staff can inspect the supplier commitments and quantities still due. - Received purchase orders use closing rather than cancellation. concepts: - CON-COM-ORD-006 actors: - ACT-COM-019 - ACT-COM-015 surfaces: - api preconditions: [] postconditions: [] permissions: - key: commerce.purchasing.read where_checked: api scope: tenant - key: commerce.purchasing.create where_checked: api scope: tenant - key: commerce.purchasing.update where_checked: api scope: tenant - key: commerce.purchasing.delete where_checked: api scope: tenant - key: commerce.purchasing.bulk where_checked: api scope: tenant rules: - id: BR-CAP-COM-ORD-017-01 proved_by: [ATS-COM-ORD-017-01, ATS-COM-ORD-018-18, TST-COM-ORD-155] statement: >- Vendor e-mail is normalized to lower case, replacement requires the current version and supplier countries must be assigned two-letter country codes. kind: validation enforced_at: - api - database must_prove: true provenance: test source: >- services-commerce:modules/purchasing/tests/e2e/purchasing.e2e.spec.js#refuses a supplier address whose country is not an ISO 3166-1 code (ZZ), on a create and on a replacement, 400 naming address.country origin: >- services-commerce:docs/migrations/purchasing/README.md#D-P8P-16. A supplier's country is one of ISO 3166-1 alpha-2's assigned codes (Q07, Andrew 2026-10-19) - id: BR-CAP-COM-ORD-017-02 proved_by: [ATS-COM-ORD-017-02, TST-COM-ORD-155] statement: A vendor referenced by purchase orders or receipts cannot be deleted. kind: invariant enforced_at: - service - database must_prove: true provenance: test source: >- services-commerce:modules/purchasing/tests/e2e/purchasing.e2e.spec.js#refuses a receipt against the received order 409, a receipt line with no quantity 400, and the vendor’s delete 409 origin: none - id: BR-CAP-COM-ORD-017-03 proved_by: [ATS-COM-ORD-017-03, TST-COM-ORD-155] statement: >- Staff draft a numbered purchase order and replace it only while draft at the version read, accepting read-only fields on round-trip but rejecting unknown line fields before issue. kind: lifecycle enforced_at: - api - service must_prove: true provenance: test source: >- services-commerce:modules/purchasing/tests/e2e/purchasing.e2e.spec.js#replaces the draft at the version read with the record exactly as it was read, read-only line columns included, and answers the same lines one version on origin: none - id: BR-CAP-COM-ORD-017-04 proved_by: [ATS-COM-ORD-017-04, ATS-COM-ORD-017-07, TST-COM-ORD-155, TST-COM-ORD-160, TST-COM-ORD-162] statement: >- A purchase order can be cancelled before receipt in draft or issued state; after receipt it can be closed to cancel the remainder, and individual open line quantities can also be cancelled. kind: lifecycle enforced_at: - service must_prove: true provenance: test source: >- services-commerce:modules/purchasing/tests/unit/orders/purchase-order-cancel.spec.js#tells a partially received order to close instead, not its status origin: none - id: BR-CAP-COM-ORD-017-05 proved_by: [ATS-COM-ORD-017-05, TST-COM-ORD-161] statement: The remaining purchase quantity equals ordered units minus received and cancelled units. kind: calculation enforced_at: - service must_prove: true provenance: test source: >- services-commerce:modules/purchasing/tests/unit/cost/cost-rules.spec.js#is the ordered quantity less what was received and cancelled origin: none - id: BR-CAP-COM-ORD-017-06 proved_by: [ATS-COM-ORD-017-06, TST-COM-ORD-155] statement: >- Purchasing readers can inspect records but cannot change them, with application access, security context and workspace isolation enforced on the API. kind: permission enforced_at: - api must_prove: true provenance: test source: >- services-commerce:modules/purchasing/tests/e2e/purchasing.e2e.spec.js#lets a reader list and read, refuses the reader every write 403 permission_missing, a denied principal 403 app_not_permitted, no context 401, and another tenant 404 origin: none - id: BR-CAP-COM-ORD-017-07 proved_by: [] statement: 'Purchase orders distinguish draft, issued, partially received, received, closed and cancelled states.' kind: lifecycle enforced_at: - database must_prove: false provenance: observed source: 'services-commerce:modules/purchasing/db/purchase-orders.table.ts:PURCHASE_ORDER_STATUSES' origin: none scenarios: - id: SC-CAP-COM-ORD-017-01 given: A supplier commitment covers one hundred tote bags. when: 'Staff receive sixty, then the remainder with freight, and close the order.' then: 'The purchase progresses through partial receipt, completed receipt and closing.' provenance: unknown source: FND-COM-ORD-032 edge_cases: [] constraints: [] depends_on: [] related: - CAP-COM-ORD-018 journeys: - JNY-COM-ORD-006 open_questions: - OQ-COM-ORD-004 evidence: - >- Examined reference: services-commerce:docs/migrations/purchasing/README.md#D-P8P-16. A supplier's country is one of ISO 3166-1 alpha-2's assigned codes (Q07, Andrew 2026-10-19) - >- Examined reference: services-commerce:modules/purchasing/db/purchase-orders.table.ts:PURCHASE_ORDER_STATUSES - >- Examined reference: services-commerce:modules/purchasing/tests/e2e/purchasing.e2e.spec.js#lets a reader list and read, refuses the reader every write 403 permission_missing, a denied principal 403 app_not_permitted, no context 401, and another tenant 404 - >- Examined reference: services-commerce:modules/purchasing/tests/e2e/purchasing.e2e.spec.js#refuses a receipt against the received order 409, a receipt line with no quantity 400, and the vendor’s delete 409 - >- Examined reference: services-commerce:modules/purchasing/tests/e2e/purchasing.e2e.spec.js#refuses a supplier address whose country is not an ISO 3166-1 code (ZZ), on a create and on a replacement, 400 naming address.country - >- Examined reference: services-commerce:modules/purchasing/tests/e2e/purchasing.e2e.spec.js#replaces the draft at the version read with the record exactly as it was read, read-only line columns included, and answers the same lines one version on - >- Examined reference: services-commerce:modules/purchasing/tests/unit/cost/cost-rules.spec.js#is the ordered quantity less what was received and cancelled - >- Examined reference: services-commerce:modules/purchasing/tests/unit/orders/purchase-order-cancel.spec.js#tells a partially received order to close instead, not its status 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-003, TC-PI-005, TC-PRV-001, TC-PRV-002] exercised_by: [FAS-COM-ORD-07-01, FAS-COM-ORD-07-02, FAS-COM-ORD-07-03, FAS-COM-ORD-07-04, FAS-COM-ORD-07-05] suites: [TST-COM-ORD-155, TST-COM-ORD-160, TST-COM-ORD-161, TST-COM-ORD-162] --- # Arrange vendor stock purchases ## Purpose Purchasing staff record supplier commitments and monitor stock that remains due. The purchase order separates the agreed supply from later receipts. ## How It Works Purchasing staff maintain the vendor information used for a supply order. They draft the expected items, quantities and costs before issuing the order. Version checks prevent an old draft from replacing newer work. Receipts later update how much of each commitment has arrived. Staff can cancel an unreceived commitment or close its remaining quantities after partial receipt. Readers can inspect the supplier and purchase order without purchasing authority. ## Relationships Receiving consumes the vendor commitment and updates its delivered quantities, while inventory and costing retain the resulting stock facts.