---
id: CAP-ACC-TRX-008
title: Allocate and relocate received money
feature: FEAT-ACC-TRX-03
product_area: accounting
module: transactions
revision: 1
status: draft
product_intent: proposed
implementation_evidence: observed
supersedes:
  - CAP-ACC-PAY-004
  - CAP-ACC-PAY-005
source_sha:
  services-accounting: f47cb263875bbc0c5640fba7dae6785ec32695f8
  react-console: baf6dae382d6f41dce976c7f848667ccc37e076f
intent_sources:
  - 'services-accounting:docs/milestones/plans/ACCT-M2-plan.md#D1'
  - 'services-accounting:docs/milestones/plans/ACCT-M2-plan.md#D2'
  - 'services-accounting:docs/milestones/plans/ACCT-M2-plan.md#D4'
  - 'services-accounting:docs/milestones/plans/ACCT-M2-plan.md#D6'
  - 'services-accounting:docs/architecture/accounting-2.0/02-decisions.md#M2-9'
purpose: Staff put held receipts against the correct customer debt while retaining earlier allocation history.
outcomes:
  - Staff put held receipts against the correct customer debt while retaining earlier allocation history.
  - Both changes commit together. A first payment can recognize a previously unconverted quote.
concepts:
  - CON-ACC-TRX-003
  - CON-ACC-TRX-001
actors:
  - ACT-ACC-012
  - ACT-ACC-021
surfaces:
  - console
  - api
permissions:
  - key: accounting.payments.update
    where_checked: api
    scope: tenant
  - key: accounting.payments.read
    where_checked: api
    scope: tenant
rules:
  - id: BR-CAP-ACC-TRX-008-01
    proved_by: [ATS-ACC-TRX-004-07, ATS-ACC-TRX-008-01, ATS-ACC-TRX-010-07, TST-ACC-TRX-081]
    statement: >-
      Allocations target issued eligible invoice lines in the payment’s unit and currency; drafts and void
      invoices cannot receive money.
    kind: validation
    enforced_at:
      - service
      - database
    must_prove: true
    provenance: test
    source: >-
      services-accounting:modules/transactions/tests/integration/services/payments/receive-offline.integration.spec.js#it
      refuses an invoice of another unit (business_unit_mismatch)
    origin: none
    note: >-
      The cited build recommendation does not establish Product approval; the authority gap remains open in
      FND-ACC-TRX-035.
  - id: BR-CAP-ACC-TRX-008-02
    proved_by: [ATS-ACC-TRX-008-02, ATS-ACC-TRX-010-07, TST-ACC-TRX-072]
    statement: >-
      Every allocation path restricts payment to the receipt’s own customer until a later multi-customer model
      is implemented.
    kind: policy
    enforced_at:
      - service
    must_prove: true
    provenance: test
    source: >-
      services-accounting:modules/transactions/tests/integration/services/payments/customer-guard.integration.spec.js#it
      refuses allocating unapplied money to another customer’s invoice, leaving the payment unapplied
    origin: none
    note: >-
      The cited build recommendation does not establish Product approval; the authority gap remains open in
      FND-ACC-TRX-035.
  - id: BR-CAP-ACC-TRX-008-03
    proved_by: [ATS-ACC-TRX-008-03, TST-ACC-TRX-070, TST-ACC-TRX-081]
    statement: >-
      A line target receives its stated amount, while an invoice target distributes the amount by line payment
      priority up to each outstanding balance.
    kind: calculation
    enforced_at:
      - service
    must_prove: true
    provenance: test
    source: >-
      services-accounting:modules/transactions/tests/integration/services/payments/allocate.integration.spec.js#it
      spreads the invoice target by pay priority: the second invoice’s first line takes 5000
    origin: none
    note: >-
      The cited build recommendation does not establish Product approval; the authority gap remains open in
      FND-ACC-TRX-035.
  - id: BR-CAP-ACC-TRX-008-04
    proved_by: [ATS-ACC-TRX-003-12, ATS-ACC-TRX-004-07, ATS-ACC-TRX-006-10, ATS-ACC-TRX-007-12, ATS-ACC-TRX-008-04, ATS-ACC-TRX-008-09, ATS-ACC-TRX-009-12, ATS-ACC-TRX-020-09, TST-ACC-TRX-070, TST-ACC-TRX-256]
    statement: >-
      Allocation cannot exceed either a line’s balance or the payment’s available money, including concurrent
      attempts protected by database constraints.
    kind: invariant
    enforced_at:
      - service
      - database
    must_prove: true
    provenance: test
    source: >-
      services-accounting:modules/transactions/tests/integration/services/payments/allocate.integration.spec.js#it
      serialize, and the second is refused by the database’s balance CHECK, not by code
    origin: none
    note: >-
      The cited build recommendation does not establish Product approval; the authority gap remains open in
      FND-ACC-TRX-035.
  - id: BR-CAP-ACC-TRX-008-05
    proved_by: [ATS-ACC-TRX-008-05, ATS-ACC-TRX-008-09, TST-ACC-TRX-070]
    statement: >-
      Allocation history accepts additions only; taking money away requires an opposite entry referring to the
      original.
    kind: invariant
    enforced_at:
      - database
    must_prove: true
    provenance: test
    source: >-
      services-accounting:modules/transactions/tests/integration/services/payments/allocate.integration.spec.js#it
      refuses an UPDATE of an allocation row
    origin: 'services-accounting:docs/architecture/accounting-2.0/02-decisions.md#D-01'
  - id: BR-CAP-ACC-TRX-008-06
    proved_by: [ATS-ACC-TRX-003-12, ATS-ACC-TRX-006-10, ATS-ACC-TRX-008-06, ATS-ACC-TRX-008-09, TST-ACC-TRX-070, TST-ACC-TRX-242]
    statement: >-
      Reallocation negates selected live applications and applies the resulting available money to new targets
      atomically; an already reversed application is ineligible.
    kind: lifecycle
    enforced_at:
      - service
    must_prove: true
    provenance: test
    source: >-
      services-accounting:modules/transactions/tests/integration/services/payments/allocate.integration.spec.js#it
      writes a reversing row for the 5000 and a new row for the 4000, the original marked reversed in full
    origin: none
    note: >-
      The cited build recommendation does not establish Product approval; the authority gap remains open in
      FND-ACC-TRX-035.
  - id: BR-CAP-ACC-TRX-008-07
    proved_by: [ATS-ACC-TRX-007-12, ATS-ACC-TRX-008-07, TST-ACC-TRX-070]
    statement: 'Only live payments can be allocated; voided, returned and charged-back receipts have no usable money.'
    kind: validation
    enforced_at:
      - service
      - database
    must_prove: true
    provenance: test
    source: >-
      services-accounting:modules/transactions/tests/integration/services/payments/allocate.integration.spec.js#it
      refuses allocating a voided payment (payment_not_live)
    origin: none
    note: >-
      The cited build recommendation does not establish Product approval; the authority gap remains open in
      FND-ACC-TRX-035.
  - id: BR-CAP-ACC-TRX-008-08
    proved_by: [ATS-ACC-TRX-008-08, TST-ACC-TRX-081]
    statement: The first payment against an issued pro forma recognizes it as a real invoice within the same operation.
    kind: lifecycle
    enforced_at:
      - service
    must_prove: true
    provenance: test
    source: >-
      services-accounting:modules/transactions/tests/integration/services/payments/receive-offline.integration.spec.js#it
      converts an unconverted pro forma the first payment names, in the payment’s batch, and pays it
      (Commerce’s first payment makes it real)
    origin: none
    note: >-
      The cited build recommendation does not establish Product approval; the authority gap remains open in
      FND-ACC-TRX-035.
  - id: BR-CAP-ACC-TRX-008-09
    proved_by: []
    statement: >-
      Later allocation chooses the requested batch, otherwise the payment’s still-open batch, otherwise the
      unit’s assigned batch.
    kind: policy
    enforced_at:
      - service
    must_prove: false
    provenance: documented
    source: 'services-accounting:docs/accounting/payments.md#Routes'
    origin: none
    note: >-
      The cited build recommendation does not establish Product approval; the authority gap remains open in
      FND-ACC-TRX-035.
scenarios:
  - id: SC-CAP-ACC-TRX-008-01
    given: A receipt paid the wrong invoice.
    when: Move its allocation from the payment record.
    then: 'The original and opposing entries remain alongside the replacement, which settles the intended invoice.'
    provenance: test
    source: 'react-console:acceptance/accounting/playwright/journeys/payments/ACT-ACC-0304.spec.ts#ACT-ACC-0304'
  - id: SC-CAP-ACC-TRX-008-02
    given: Only 10.00 remains available on one receipt.
    when: Two staff submit applications simultaneously.
    then: Database protection permits one spend and rejects the competing request.
    provenance: test
    source: 'react-console:acceptance/accounting/playwright/journeys/payments/ACT-ACC-0321.spec.ts#ACT-ACC-0321'
edge_cases: []
constraints:
  - One allocation request names at most five hundred targets.
depends_on:
  - CAP-ACC-TRX-006
related:
  - CAP-ACC-TRX-007
  - CAP-ACC-TRX-009
  - CAP-ACC-TRX-011
journeys:
  - JNY-ACC-TRX-002
evidence:
  - >-
    services-accounting at f47cb263875bbc0c5640fba7dae6785ec32695f8:
    modules/transactions/aws/api/payments.routes.ts (allocatePayment, reallocatePayment,
    listUnappliedPayments); services/allocation-plan.ts; services/payments/payment-allocate.ts,
    allocation-rows.ts; services/persistence/allocation-targets.ts; db/payment-allocations.table.ts;
    docs/accounting/payments.md ("Allocations", "The payer");
    docs/debt/payment-model-one-receipt-many-customers.md; tests integration/services/payments/allocate,
    customer-guard, receive-offline.
  - >-
    react-console at baf6dae382d6f41dce976c7f848667ccc37e076f:
    components/accounting/payments/payment-detail-screen.tsx (Allocate, Reallocate); journeys ACT-ACC-0300,
    0304, 0321; inventory rules RUL-ACC-PAY-005, 006, 015 to 017, 030.
controls: [TC-IAM-001, TC-IAM-002, TC-IAM-004, TC-IAM-005, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-006, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-TEN-004, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-PI-001, TC-PI-003, TC-PI-005, TC-PRV-001, TC-PRV-002]
exercised_by: [FAS-ACC-TRX-03-01, FAS-ACC-TRX-03-02, FAS-ACC-TRX-03-03, FAS-ACC-TRX-03-04]
suites: [TST-ACC-TRX-070, TST-ACC-TRX-072, TST-ACC-TRX-081, TST-ACC-TRX-242, TST-ACC-TRX-256]
---

# Allocate and relocate received money

## Purpose

Staff put held receipts against the correct customer debt while retaining earlier allocation history.

## How It Works

Staff choose invoice or line targets for available receipt value. Accounting restricts targets to the applicable customer and financial context. Invoice targets distribute value according to line priority. An application that would overspend either side is refused. Reallocation writes opposite entries for selected old applications before placing the available value again. Both changes commit together. A first payment can recognize a previously unconverted quote.

## Relationships

- Record receipts collected outside Rhythm supplies or continues the related financial work.
- Collect processor payments and resolve uncertainty supplies or continues the related financial work.
- Complete invoice settlement with credit and money supplies or continues the related financial work.
- Provide and spend customer credit supplies or continues the related financial work.