--- id: CAP-COM-ORD-016 title: Authorize returns and settle received goods feature: FEAT-COM-ORD-06 product_area: commerce module: orders revision: 1 status: draft product_intent: proposed implementation_evidence: observed supersedes: - CAP-COM-PPU-013 - CAP-COM-PPU-014 - CAP-COM-PPU-015 - CAP-COM-PPU-016 - CAP-COM-PPU-017 - CAP-COM-PPU-018 - CAP-COM-PPU-022 - CAP-COM-PPU-025 - CAP-COM-REG-038 - CAP-COM-REG-044 - CAP-COM-PPU-021 source_sha: services-commerce: c8b66a98e2490617aec38ba5c8165dd9bd0a8f9b react-console: baf6dae382d6f41dce976c7f848667ccc37e076f intent_sources: - 'services-commerce:docs/migrations/post-purchase/README.md#D-P7-32' purpose: Returned goods follow an authorization and a financial treatment appropriate to their return terms. outcomes: - An eligible return supplies an authorization number and deadline. - Return settlement follows the selected trigger and applicable fees. concepts: - CON-COM-ORD-005 - CON-COM-ORD-002 actors: - ACT-COM-014 - ACT-COM-016 - ACT-COM-017 surfaces: - console - portal - api preconditions: [] postconditions: [] permissions: - key: commerce.returns.read where_checked: api scope: tenant - key: commerce.returns.create where_checked: api scope: tenant - key: commerce.returns.update where_checked: api scope: tenant - key: commerce.returns.approve where_checked: api scope: tenant - key: commerce.returns.override where_checked: service scope: tenant - key: commerce.return-policies.read where_checked: api scope: tenant - key: commerce.return-policies.create where_checked: api scope: tenant - key: commerce.return-policies.delete where_checked: api scope: tenant - key: commerce.return-policies.update where_checked: api scope: tenant - key: commerce.return-policies.bulk where_checked: api scope: tenant rules: - id: BR-CAP-COM-ORD-016-01 proved_by: [ATS-COM-ORD-016-01, ATS-COM-ORD-016-13, TST-COM-ORD-084] statement: >- Returns require an accepted order and available line quantity, refusing placed orders, excess quantities, unauthorized parties and another workspace’s records. kind: validation enforced_at: - api - service must_prove: true provenance: test source: >- services-commerce:modules/orders/tests/e2e/returns.e2e.spec.js#refuses a placed order 409 order_not_returnable, more units than the line has (rejected), another member 403, a reader 403, another tenant 404 origin: none - id: BR-CAP-COM-ORD-016-02 proved_by: [ATS-COM-ORD-016-02, TST-COM-ORD-142] statement: >- Return policy resolves from product, store, workspace and built-in defaults, with frozen promises able to improve the chosen terms; the built-in policy uses thirty days, outside-window review and refund on receipt without a fee. kind: calculation enforced_at: - service must_prove: true provenance: test source: >- services-commerce:modules/orders/tests/unit/returns/return-policy.spec.js#picks the most specific configured policy, else the built-in default, and loosens it by the frozen terms origin: none - id: BR-CAP-COM-ORD-016-03 proved_by: [ATS-COM-ORD-014-18, ATS-COM-ORD-016-03, TST-COM-ORD-084] statement: >- An eligible in-window request immediately receives a numbered return authorization with its permitted lines, deadline and return instructions. kind: lifecycle enforced_at: - service must_prove: true provenance: test source: >- services-commerce:modules/orders/tests/e2e/returns.e2e.spec.js#authorizes at once under the built-in policy: the RMA numbered with its deadline, the lines authorized, the customer told to send it back origin: none - id: BR-CAP-COM-ORD-016-04 proved_by: [ATS-COM-ORD-016-04, TST-COM-ORD-084] statement: A late customer return waits for an approver to authorize or reject it with a reason. kind: policy enforced_at: - service must_prove: true provenance: test source: >- services-commerce:modules/orders/tests/e2e/returns.e2e.spec.js#holds the member’s request for approval; the approver authorizes it and the RMA is issued origin: none - id: BR-CAP-COM-ORD-016-05 proved_by: [ATS-COM-ORD-016-05, TST-COM-ORD-084] statement: Final-sale items require an administrator override to become returnable. kind: policy enforced_at: - service must_prove: true provenance: test source: >- services-commerce:modules/orders/tests/e2e/returns.e2e.spec.js#rejects the member with final_sale; the administrator’s override authorizes it origin: none - id: BR-CAP-COM-ORD-016-06 proved_by: [ATS-COM-ORD-016-06, ATS-COM-ORD-016-12, ATS-COM-ORD-018-17, TST-COM-ORD-084] statement: >- Settlement follows the chosen authorization, receipt or inspection trigger, with receipt-based returns closing after all goods and money are processed and partial receipts remaining open. kind: lifecycle enforced_at: - service must_prove: true provenance: test source: >- services-commerce:modules/orders/tests/e2e/returns.e2e.spec.js#takes the warehouse’s receipt: the goods back on the line, the memo and the refund run, the document completed and the RMA closed origin: none - id: BR-CAP-COM-ORD-016-07 proved_by: [ATS-COM-ORD-016-07, TST-COM-ORD-084] statement: >- Restocking fees use a separate fee invoice paid from freed money, with the remainder refunded; staff can choose credit while a customer cannot select the financial action. kind: calculation enforced_at: - service must_prove: true provenance: test source: >- services-commerce:modules/orders/tests/e2e/returns.e2e.spec.js#charges the policy’s 10% restocking fee as an invoice paid from the freed money, and refunds the rest origin: none - id: BR-CAP-COM-ORD-016-08 proved_by: [ATS-COM-ORD-016-08, TST-COM-ORD-084, TST-COM-ORD-142] statement: >- A customer-paid purchased return label uses the configured label fee product and reduces only the refund remaining after other fees; customer deductions do not apply to organization-paid or unpurchased labels. kind: calculation enforced_at: - service must_prove: true provenance: test source: >- services-commerce:modules/orders/tests/e2e/returns.e2e.spec.js#invoices the label on the return label fee product, pays it from the freed money and refunds the rest origin: 'services-commerce:docs/migrations/post-purchase/README.md#D-P7-32' - id: BR-CAP-COM-ORD-016-09 proved_by: [ATS-COM-ORD-016-09, TST-COM-ORD-084] statement: >- Only one return policy occupies each product or store scope or the workspace default, malformed default scope references are refused and portal callers cannot read policy administration. kind: validation enforced_at: - api - service must_prove: true provenance: test source: >- services-commerce:modules/orders/tests/e2e/returns.e2e.spec.js#lists, reads and deletes the policy; refuses a member the policies, a second policy at the scope 400, a tenant default with a scope id 400 origin: none - id: BR-CAP-COM-ORD-016-10 proved_by: [ATS-COM-ORD-016-10, TST-COM-ORD-084] statement: >- Withdrawing an authorized return closes its authorization and informs receiving, while another active return on the same line blocks a duplicate request. kind: lifecycle enforced_at: - service must_prove: true provenance: test source: >- services-commerce:modules/orders/tests/e2e/returns.e2e.spec.js#lets the member withdraw an authorized return: the RMA closed and the streams told; a line already under a return refused meanwhile origin: none - id: BR-CAP-COM-ORD-016-11 proved_by: [ATS-COM-ORD-016-11, TST-COM-ORD-142] statement: >- A frozen promise that the organization pays the return label prevents a later policy from charging that label to the customer. kind: invariant enforced_at: - service must_prove: true provenance: test source: >- services-commerce:modules/orders/tests/unit/returns/return-policy.spec.js#keeps a label the frozen terms promised at the tenant’s cost from being charged to the customer later origin: none - id: BR-CAP-COM-ORD-016-12 proved_by: [] statement: Return-policy administration supports creation and deletion without an edit operation. kind: policy enforced_at: - api must_prove: false provenance: observed source: 'services-commerce:modules/orders/aws/api/post-purchase.routes.ts:postPurchaseRoutes' origin: none note: Finding 018 records the absence of a return-policy editing operation. scenarios: - id: SC-CAP-COM-ORD-016-01 given: Two purchased mugs arrive damaged. when: The customer requests their return and receiving reports and inspects the goods. then: >- The authorization, receipt, inspection and settlement remain connected, with a stock disposition for the returned goods. provenance: unknown source: FND-COM-ORD-032 edge_cases: [] constraints: [] depends_on: - CAP-COM-ORD-006 - CAP-COM-ORD-014 related: - CAP-COM-ORD-018 journeys: [] open_questions: [] evidence: - 'Examined reference: services-commerce:docs/migrations/post-purchase/README.md#D-P7-32' - 'Examined reference: services-commerce:modules/orders/aws/api/post-purchase.routes.ts:postPurchaseRoutes' - >- Examined reference: services-commerce:modules/orders/tests/e2e/returns.e2e.spec.js#authorizes at once under the built-in policy: the RMA numbered with its deadline, the lines authorized, the customer told to send it back - >- Examined reference: services-commerce:modules/orders/tests/e2e/returns.e2e.spec.js#charges the policy’s 10% restocking fee as an invoice paid from the freed money, and refunds the rest - >- Examined reference: services-commerce:modules/orders/tests/e2e/returns.e2e.spec.js#holds the member’s request for approval; the approver authorizes it and the RMA is issued - >- Examined reference: services-commerce:modules/orders/tests/e2e/returns.e2e.spec.js#invoices the label on the return label fee product, pays it from the freed money and refunds the rest - >- Examined reference: services-commerce:modules/orders/tests/e2e/returns.e2e.spec.js#lets the member withdraw an authorized return: the RMA closed and the streams told; a line already under a return refused meanwhile - >- Examined reference: services-commerce:modules/orders/tests/e2e/returns.e2e.spec.js#lists, reads and deletes the policy; refuses a member the policies, a second policy at the scope 400, a tenant default with a scope id 400 - >- Examined reference: services-commerce:modules/orders/tests/e2e/returns.e2e.spec.js#refuses a placed order 409 order_not_returnable, more units than the line has (rejected), another member 403, a reader 403, another tenant 404 - >- Examined reference: services-commerce:modules/orders/tests/e2e/returns.e2e.spec.js#rejects the member with final_sale; the administrator’s override authorizes it - >- Examined reference: services-commerce:modules/orders/tests/e2e/returns.e2e.spec.js#takes the warehouse’s receipt: the goods back on the line, the memo and the refund run, the document completed and the RMA closed - >- Examined reference: services-commerce:modules/orders/tests/unit/returns/return-policy.spec.js#keeps a label the frozen terms promised at the tenant’s cost from being charged to the customer later - >- Examined reference: services-commerce:modules/orders/tests/unit/returns/return-policy.spec.js#picks the most specific configured policy, else the built-in default, and loosens it by the frozen terms 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-TEN-004, TC-CRY-001, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-DAT-004, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-PI-001, TC-PI-003, TC-PI-005, TC-VEN-001, TC-VEN-002, TC-VEN-003, TC-PRV-001, TC-PRV-002] exercised_by: [FAS-COM-ORD-06-01, FAS-COM-ORD-06-02, FAS-COM-ORD-06-04, FAS-COM-ORD-06-05] suites: [TST-COM-ORD-084, TST-COM-ORD-142] --- # Authorize returns and settle received goods ## Purpose Returned goods follow an authorization and a financial treatment appropriate to their return terms. Staff can explain progress from permission to send goods back through final settlement. ## How It Works The requester asks to return units from an accepted order. Commerce resolves the applicable policy and evaluates the request against the preserved sale terms. An approved request issues the information receiving needs to recognize the returned goods. Receiving and inspection report progress against that authorization. Settlement occurs at the policy’s chosen point and includes configured fees. The requester can distinguish approval, receipt and completed financial treatment. ## Relationships Order inspection supplies sale facts, return policy supplies terms, the neighbouring receiving workflow reports goods and Accounting settles the selected financial action.