---
id: CAP-ACC-BAT-004
title: Use the batch’s permitted lifecycle actions
feature: FEAT-ACC-BAT-01
product_area: accounting
module: batches
revision: 1
status: draft
product_intent: proposed
implementation_evidence: observed
supersedes:
- inventory CAP-ACC-BAT-002
- inventory RUL-ACC-BAT-008
- inventory RUL-ACC-BAT-009
- inventory RUL-ACC-BAT-010
- inventory RUL-ACC-BAT-011
- inventory RUL-ACC-BAT-014
- inventory RUL-ACC-BAT-062
- journey ACT-ACC-0503
- journey ACT-ACC-0540
- journey ACT-ACC-0542
source_sha:
  services-accounting: f47cb263875bbc0c5640fba7dae6785ec32695f8
  react-console: baf6dae382d6f41dce976c7f848667ccc37e076f
intent_sources:
- services-accounting:docs/migrations/transaction-processing/batches/README.md#Status as actions (job tp-batch-lifecycle,
  Andrew's UI brief of 2026-10-15)
purpose: Staff change a batch’s working state through the actions available to their role.
outcomes:
- Staff can retire or restore collections through the available lifecycle actions.
concepts:
- CON-ACC-BAT-001
actors:
- ACT-ACC-012
- ACT-ACC-006
- ACT-ACC-007
surfaces:
- console
- api
permissions:
- key: accounting.batches.read
  where_checked: api
  scope: tenant
- key: accounting.batches.update
  where_checked: api
  scope: tenant
- key: accounting.batch-postings.post
  where_checked: api
  scope: tenant
- key: accounting.batch-postings.unpost
  where_checked: api
  scope: tenant
rules:
- id: BR-CAP-ACC-BAT-004-01
  proved_by: [ATS-ACC-BAT-004-01, ATS-ACC-BAT-004-12, ATS-ACC-BAT-013-15, TST-ACC-BAT-002, TST-ACC-BAT-055, TST-ACC-BAT-060, TST-ACC-BAT-085]
  statement: The public interface changes status through Close, Reopen, Archive, Unarchive, Post and Unpost rather
    than a status field edit.
  kind: lifecycle
  enforced_at:
  - api
  - service
  must_prove: true
  provenance: test
  source: services-accounting:modules/batches/tests/e2e/batch-actions.e2e.spec.js#answers each status action with
    the updated batch
  origin: services-accounting:docs/migrations/transaction-processing/batches/README.md#Status as actions (Andrew's
    UI brief of 2026-10-15)
- id: BR-CAP-ACC-BAT-004-02
  proved_by: [ATS-ACC-BAT-004-01, ATS-ACC-BAT-004-10, ATS-ACC-BAT-005-08, TST-ACC-BAT-002, TST-ACC-BAT-055, TST-ACC-BAT-060, TST-ACC-BAT-085]
  statement: Close accepts an Open batch and rejects other starting states.
  kind: lifecycle
  enforced_at:
  - service
  must_prove: true
  provenance: test
  source: services-accounting:modules/batches/tests/integration/services/persistence/batches.integration.spec.js#refuses
    closing a batch that is not open
  origin: services-accounting:docs/migrations/transaction-processing/batches/README.md#Status as actions (Andrew's
    UI brief of 2026-10-15)
- id: BR-CAP-ACC-BAT-004-03
  proved_by: [ATS-ACC-BAT-004-02, ATS-ACC-BAT-004-11, ATS-ACC-BAT-008-07, TST-ACC-BAT-085]
  statement: Reopen accepts Closed, Verified and Error, clears recorded errors, and leaves posted and archived batches
    to their separate Unpost and Unarchive actions.
  kind: lifecycle
  enforced_at:
  - service
  must_prove: true
  provenance: test
  source: services-accounting:modules/batches/tests/integration/services/persistence/batches.integration.spec.js#clears
    the errors of an errored batch on reopen, so the open batch carries none (journey ACT-ACC-0521)
  origin: services-accounting:docs/migrations/transaction-processing/batches/README.md#Status as actions (Andrew's
    UI brief of 2026-10-15)
- id: BR-CAP-ACC-BAT-004-04
  proved_by: [ATS-ACC-BAT-004-03, TST-ACC-BAT-002, TST-ACC-BAT-055, TST-ACC-BAT-085]
  statement: Archive accepts Open or Closed, stops document intake and posting, and clears the automatic close.
  kind: lifecycle
  enforced_at:
  - service
  must_prove: true
  provenance: test
  source: services-accounting:modules/batches/tests/integration/services/persistence/batches.integration.spec.js#refuses
    archiving a posted batch 409
  origin: services-accounting:docs/migrations/transaction-processing/batches/README.md#Status as actions (Andrew's
    UI brief of 2026-10-15)
- id: BR-CAP-ACC-BAT-004-05
  proved_by: [ATS-ACC-BAT-003-12, ATS-ACC-BAT-004-03, ATS-ACC-BAT-004-09, TST-ACC-BAT-002, TST-ACC-BAT-055, TST-ACC-BAT-085]
  statement: Unarchive opens the batch without restoring the state it had before archive.
  kind: lifecycle
  enforced_at:
  - service
  must_prove: true
  provenance: test
  source: services-accounting:modules/batches/tests/integration/services/persistence/batches.integration.spec.js#archives
    an open batch and a closed one, and unarchives to open
  origin: none
- id: BR-CAP-ACC-BAT-004-06
  proved_by: [ATS-ACC-BAT-004-04, ATS-ACC-BAT-004-13, ATS-ACC-BAT-004-15, ATS-ACC-BAT-016-09, TST-ACC-BAT-119]
  statement: The action catalogue offers Post, Close and Archive for Open; Post, Reopen and Archive for Closed;
    Reopen for Verified; Post and Reopen for Error; Unarchive for Archived; and Unpost for Posted, Downloaded or
    posting work unchanged for over an hour.
  kind: lifecycle
  enforced_at:
  - service
  must_prove: true
  provenance: test
  source: services-accounting:modules/batches/tests/unit/actions/batch-actions.spec.js#offers a batch posting for
    half an hour nothing, and one stuck in posting for over an hour unpost
  origin: none
- id: BR-CAP-ACC-BAT-004-07
  proved_by: [ATS-ACC-BAT-004-05, TST-ACC-BAT-027, TST-ACC-BAT-055, TST-ACC-BAT-119]
  statement: Lifecycle actions require update permission, Post requires posting permission and Unpost requires unposting
    permission, with unauthorized actions omitted and execution refused before mutation.
  kind: permission
  enforced_at:
  - api
  - service
  - console
  must_prove: true
  provenance: test
  source: services-accounting:modules/batches/tests/unit/actions/batch-actions.spec.js#refuses a caller without
    the action’s permission, 403, before the command runs
  origin: none
- id: BR-CAP-ACC-BAT-004-08
  proved_by: [ATS-ACC-BAT-004-06, TST-ACC-BAT-003, TST-ACC-BAT-085, TST-ACC-BAT-119]
  statement: An update-locked batch lists the applicable actions as disabled with a lock explanation and rejects
    their execution.
  kind: policy
  enforced_at:
  - service
  - console
  must_prove: true
  provenance: test
  source: services-accounting:modules/batches/tests/unit/actions/batch-actions.spec.js#lists a locked batch’s status
    actions with the refusal the command would answer as disabled_reason
  origin: none
- id: BR-CAP-ACC-BAT-004-09
  proved_by: [ATS-ACC-BAT-004-07, ATS-ACC-BAT-004-14, ATS-ACC-BAT-020-08, TST-ACC-BAT-063, TST-ACC-BAT-074]
  statement: System batches offer no ordinary action and reject every such action because fiscal close and reopen
    control them.
  kind: policy
  enforced_at:
  - service
  must_prove: true
  provenance: test
  source: services-accounting:modules/batches/tests/e2e/system-batches.e2e.spec.js#offers an administrator no action
    for the system batch
  origin: none
- id: BR-CAP-ACC-BAT-004-10
  proved_by: []
  statement: Post, Archive and Unpost require confirmation, and Post warns when an Open batch will stop accepting
    documents.
  kind: policy
  enforced_at:
  - service
  - console
  must_prove: false
  provenance: test
  source: services-accounting:modules/batches/tests/unit/actions/batch-actions.spec.js#answers an open batch’s actions
    with their labels, placements, targets, confirmations and the warning
  origin: none
- id: BR-CAP-ACC-BAT-004-11
  proved_by: [ATS-ACC-BAT-004-08, TST-ACC-BAT-055]
  statement: Action execution rejects an unknown action or an extra batch reference, and accepts a reason or note
    without retaining it.
  kind: validation
  enforced_at:
  - api
  must_prove: true
  provenance: test
  source: services-accounting:modules/batches/tests/e2e/batch-actions.e2e.spec.js#refuses an action the batch has
    not 400, naming the actions
  origin: none
scenarios:
- id: SC-CAP-ACC-BAT-004-01
  given: The daily receivables batch is Open with its collected documents.
  when: Staff select Close from its actions.
  then: The page presents Closed and offers the subsequent permitted actions.
  provenance: documented
  source: services-accounting:docs/milestones/walkthroughs/ACCT-M3-handoff.md#Start here (step 3)
- id: SC-CAP-ACC-BAT-004-02
  given: A reader without write permission opens an Open batch.
  when: The reader inspects the status actions.
  then: The page offers no permitted status change and an unauthorized API action is refused.
  provenance: test
  source: react-console:acceptance/accounting/playwright/journeys/batches-posting/ACT-ACC-0540.spec.ts#ACT-ACC-0540
- id: SC-CAP-ACC-BAT-004-03
  given: A batch was Closed before staff archived it.
  when: Staff choose Unarchive.
  then: It returns Open and can be closed again if needed.
  provenance: test
  source: react-console:acceptance/accounting/playwright/journeys/batches-posting/ACT-ACC-0502.spec.ts#ACT-ACC-0502
edge_cases: []
constraints: []
depends_on: []
related:
- CAP-ACC-BAT-013
- CAP-ACC-BAT-016
- CAP-ACC-BAT-008
journeys:
- JNY-ACC-BAT-001
- JNY-ACC-BAT-004
open_questions: []
evidence:
- 'Pinned services-accounting (f47cb263), examined sources: aws/api/batch-records.routes.ts (closeBatch, reopenBatch,
  archiveBatch, unarchiveBatch, listBatchActions, performBatchAction), services/actions/batch-actions.ts (BATCH_ACTIONS),
  services/persistence/batches.ts (changeStatus), services/rules/batch-rules.ts (closedStatusOf, reopenedStatusOf,
  archivedStatusOf, unarchivedStatusOf, assertNotSystemBatch); tests unit/actions/batch-actions.spec.js, e2e/batch-actions.e2e.spec.js,
  e2e/system-batches.e2e.spec.js, integration/services/persistence/batches.integration.spec.js, integration/services/close/system-batch-guard.integration.spec.js.'
- 'Pinned react-console (baf6dae3), examined sources: components/accounting/batches/batch-detail-screen.tsx (the
  header''s action menu); journeys ACT-ACC-0502, 0503, 0540.'
controls: [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-005, TC-AZ-006, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-DAT-001, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-PI-001, TC-PI-003, TC-PI-005]
exercised_by: [FAS-ACC-BAT-01-02, FAS-ACC-BAT-01-03, FAS-ACC-BAT-01-04, FAS-ACC-BAT-01-05, FAS-ACC-BAT-05-04]
suites: [TST-ACC-BAT-002, TST-ACC-BAT-003, TST-ACC-BAT-027, TST-ACC-BAT-055, TST-ACC-BAT-060, TST-ACC-BAT-063, TST-ACC-BAT-074, TST-ACC-BAT-085, TST-ACC-BAT-119]
---

# Use the batch’s permitted lifecycle actions

## Purpose

Staff change a batch’s working state through the actions available to their role.

## How It Works

The batch page asks the service which actions apply to the caller and current batch. Staff choose an offered action instead of editing the status directly. Some actions ask for confirmation before execution. Posting and unposting submit jobs whose progress can then be followed. Locks explain why an otherwise applicable action is disabled. A system batch remains under fiscal-close control and offers no ordinary transition.

## Relationships

- Related outcome: Run and monitor a batch posting job, which addresses the connected batch work.
- Related outcome: Unpost a batch for correction and replacement posting, which addresses the connected batch work.
- Related outcome: Bring waiting batches to the posting team’s attention, which addresses the connected batch work.