Rhythm 2.0 Specifications

Appearance

CAP-ACC-TRX-011Provide and spend customer credit

Markdown

CAP-ACC-TRX-011

Provide and spend customer credit

Markdown
  • DocumentDraft
  • Product intentProposed
  • ImplementationObserved

Planning

Feature
FEAT-ACC-TRX-04
Exercised by
FAS-ACC-TRX-04-01, FAS-ACC-TRX-04-02, FAS-ACC-TRX-04-03, FAS-ACC-TRX-04-04, FAS-ACC-TRX-04-05, JNY-ACC-TRX-002
Key concepts
CON-ACC-TRX-004, CON-ACC-TRX-003
Actors
ACT-ACC-012, ACT-ACC-021
Journeys
JNY-ACC-TRX-004
Related
CAP-ACC-TRX-006, CAP-ACC-TRX-009, CAP-ACC-TRX-012, CAP-ACC-TRX-013
Proved by
ATS-ACC-TRX-011

Implementation

Executable suites
TST-ACC-TRX-004, TST-ACC-TRX-037, TST-ACC-TRX-246, TST-ACC-TRX-247, TST-ACC-TRX-256, TST-ACC-TRX-257

KindCapabilityProduct areaAccountingModuleTransactionsRevision1

Read atservices-accounting f47cb263react-console baf6dae3

Provide and spend customer credit ​

Purpose ​

Staff retain customer value for later settlement without confusing it with invoice reduction.

How It Works ​

Staff create goodwill credit or transfer available receipt money into credit. Accounting retains its customer, unit, currency and available balance. Applications spend that value on eligible invoice lines. Expiry and order restrictions can prevent a requested application. Reversal restores the credit and debt through a new opposing document. Unused credit can be voided, returning payment-backed value to its source. Competing requests cannot spend the same remaining value twice.

Relationships ​

  • Record receipts collected outside Rhythm supplies or continues the related financial work.
  • Complete invoice settlement with credit and money supplies or continues the related financial work.
  • Return customer money with accountable refunds supplies or continues the related financial work.
  • Record receipts that were voided or returned supplies or continues the related financial work.

The Formal Contract

The narrative above explains; the sections below are authoritative — the rules, scenarios and tests this document binds.

Outcomes
Staff retain customer value for later settlement without confusing it with invoice reduction.Unused credit can be voided, returning payment-backed value to its source. Competing requests cannot spend the same remaining value twice.
Surfaces
consoleapi
Intent sources
services-accounting:docs/milestones/plans/ACCT-M2-plan.md#D4services-accounting:docs/milestones/plans/ACCT-M2-plan.md#D5services-accounting:docs/milestones/plans/ACCT-M2-plan.md#D6services-accounting:docs/architecture/accounting-2.0/02-decisions.md#M2-2services-accounting:docs/architecture/accounting-2.0/02-decisions.md#A-9

Controls

33 controls apply, from the corpus control catalogue.

TC-IAM-001 TC-IAM-002 TC-IAM-004 TC-IAM-005 TC-IAM-006 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-LOG-005 TC-AVL-001 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 TC-PRV-001 TC-PRV-002

Permissions

KeyChecked atScope
accounting.credits.createapitenant
accounting.credits.readapitenant
accounting.credits.updateapitenant
accounting.credit-applications.createapitenant
accounting.credit-applications.readapitenant

Business Rules

12 rules, 10 to be proved before approval. A rule's product intent is derived from its origin: 1 confirmed by a product decision, the rest inheriting this capability's proposed.

IdRuleKindEnforced atProvenance
01must prove
Proposed
Manually issued credit identifies the customer, unit, currency, reason and that unit’s liability and expense accounts.
proved by ATS-ACC-TRX-011-01, TST-ACC-TRX-004, TST-ACC-TRX-037
validationapi, service, databasetest
services-accounting:modules/transactions/tests/e2e/credits.e2e.spec.js#it refuses a manual credit without its accounts, and a payment’s credit without its payment (400)
02must prove
Proposed
Payment-backed credit inherits the payment’s customer, unit and currency and transfers no more than its unapplied value out of the payment while the credit remains live.
proved by ATS-ACC-TRX-003-12, ATS-ACC-TRX-008-09, ATS-ACC-TRX-011-02, ATS-ACC-TRX-011-10, ATS-ACC-TRX-013-10, ATS-ACC-TRX-014-09, TST-ACC-TRX-037, TST-ACC-TRX-247
calculationservice, databasetest
services-accounting:modules/transactions/tests/integration/services/credits/credits.integration.spec.js#it refuses more than the payment holds unapplied (over_application)
03must prove
Proposed
Available credit equals issued value less applications, refunds and reservations; positive balance is open, zero is used, and database checks prevent overspending.
proved by ATS-ACC-TRX-007-12, ATS-ACC-TRX-008-09, ATS-ACC-TRX-009-12, ATS-ACC-TRX-011-03, ATS-ACC-TRX-011-10, ATS-ACC-TRX-012-12, TST-ACC-TRX-037, TST-ACC-TRX-256
invariantdatabasetest
services-accounting:modules/transactions/tests/integration/services/credits/credits.integration.spec.js#it refuses more than the credit holds (insufficient_credit), the database’s CHECK, writing nothing
04must prove
Proposed
Only a numbered batched credit application puts credit on invoice lines, using payment-style target selection and producing paid status when a line is settled.
origin: services-accounting:docs/architecture/accounting-2.0/02-decisions.md#M2-2
proved by ATS-ACC-TRX-007-12, ATS-ACC-TRX-009-12, ATS-ACC-TRX-011-04, ATS-ACC-TRX-014-09, TST-ACC-TRX-037
lifecycleservice, databasetest
services-accounting:modules/transactions/tests/integration/services/credits/credits.integration.spec.js#it raises the line’s amount_paid: a line settled by store credit reads open until fully paid, then paid
05must prove
Proposed
Credit can settle invoices belonging to its own customer only.
proved by ATS-ACC-TRX-011-05, TST-ACC-TRX-037, TST-ACC-TRX-257
policyservicetest
services-accounting:modules/transactions/tests/integration/services/credits/credits.integration.spec.js#it refuses a credit of another customer than the invoice’s bill-to (credit_customer_mismatch)
06must prove
Proposed
Application rejects credit after its expiry date or outside its permitted order type, although no worker marks credits expired.
proved by ATS-ACC-TRX-011-06, TST-ACC-TRX-037
validationservicetest
services-accounting:modules/transactions/tests/integration/services/credits/credits.integration.spec.js#it refuses a credit that expired before the application date (credit_expired)
07must prove
Proposed
Concurrent applications serialize so they cannot both consume the same remaining credit.
proved by ATS-ACC-TRX-011-03, TST-ACC-TRX-037, TST-ACC-TRX-256
invariantdatabasetest
services-accounting:modules/transactions/tests/integration/services/credits/credits.integration.spec.js#it serializes two concurrent applications of one credit: one succeeds, the other is refused by the database
08must prove
Proposed
Undoing an application creates one dated opposing application with a reason, restores the credit and invoice balances, and prevents a second reversal.
proved by ATS-ACC-TRX-011-07, TST-ACC-TRX-037, TST-ACC-TRX-246
lifecycleservice, databasetest
services-accounting:modules/transactions/tests/integration/services/credits/credits.integration.spec.js#it marks the first reversed and gives the money back to the credit, which is open again
09must prove
Proposed
Voiding requires unused, unreserved and unrefunded credit before posting; payment-backed credit then restores its source payment’s available value.
proved by ATS-ACC-TRX-011-08, ATS-ACC-TRX-011-10, ATS-ACC-TRX-013-10, TST-ACC-TRX-037
lifecycleservicetest
services-accounting:modules/transactions/tests/integration/services/credits/credits.integration.spec.js#it refuses voiding a credit with money applied (credit_has_applications)
10
Proposed
Eligible customer credit is presented oldest first within its unit and currency.
policyservicetest
services-accounting:modules/transactions/tests/e2e/credits.e2e.spec.js#it lists Ada’s open credits in alpha USD, oldest first
11must prove
Proposed
Credit operations use credit authorities, while application and reversal use credit-application authorities.
proved by ATS-ACC-TRX-011-09, TST-ACC-TRX-004
permissionapitest
services-accounting:modules/transactions/tests/e2e/credits.e2e.spec.js#it is refused the application routes without their permissions (403)
12
Confirmed
Application rows and database-maintained credit amounts cannot be directly edited by the application role.
origin: services-accounting:docs/architecture/accounting-2.0/02-decisions.md#D-01
invariantdatabasetest
services-accounting:modules/transactions/tests/integration/services/credits/credits.integration.spec.js#it refuses an UPDATE and a DELETE of an application line

Scenarios

IdGivenWhenThenProvenance
01Staff want to compensate a member with goodwill value.Issue credit, pay two lines with it, then undo one application.Credit settles the selected lines and the reversal restores both its available value and the affected debt.test
react-console:acceptance/accounting/playwright/journeys/payments/ACT-ACC-0309.spec.ts#ACT-ACC-0309
02Credit and invoice belong to different members of one unit.Apply that credit directly to the unrelated invoice.Customer mismatch rejects the application without moving value.test
react-console:acceptance/accounting/playwright/journeys/payments/ACT-ACC-0322.spec.ts#ACT-ACC-0322

The Markdown files under specs/ in rhythmsoftware/rhythm-v2-docs are the canonical source of truth. This reader is a generated, read-only projection of them.

Rhythm Software