---
id: WF-MBR-MEM-018
title: Execute a billing run on the durable jobs engine
trigger: An administrator or automatic recurring occurrence executes a planned run.
product_area: membership
module: memberships
revision: 1
status: draft
design_intent: proposed
implementation_evidence: partially-observed
inference: []
source_sha:
  services-membership: 5994c270e8a37a30f848e99ba5b5ee6b87c08893
  react-console: baf6dae382d6f41dce976c7f848667ccc37e076f
implements:
  - CAP-MBR-MEM-013
  - CAP-MBR-MEM-003
moves:
  - STATE-MBR-MEM-007
  - STATE-MBR-MEM-008
  - STATE-MBR-MEM-003
crosses:
  - SVC-MBR-MEM-billing
  - SVC-MBR-MEM-commerce-participant
  - SVC-MBR-MEM-memberships
idempotency: >-
  Settled actions are not processed again. Commerce placement uses an
  action-based order key, and communication request identifiers are derived from
  the action.
concurrency: >-
  Run execution identifies one job. Database actions hold action and membership
  locks; order actions release the checking transaction before placement and
  settle afterward.
hops:
  - 'n': 1
    actor_or_service: Billing service
    action: >-
      Create the execution job and mark the run executing together, then request
      job startup after commit.
    anchor: >-
      services-membership:modules/billing/services/runs/billing-run-operations.ts:executeRun
    seam: sync
    on_failure: >-
      Reject an invalid execute request; failed startup can leave the committed
      run executing without recovery.
    left_inconsistent: A committed run can remain executing without a started job.
    observer: Batch state and assigned execution record
    provenance: unknown
    source: FND-MBR-MEM-048
  - 'n': 2
    actor_or_service: Billing run job
    action: >-
      Process planned actions in slices, repeating the execution step while work
      remains.
    anchor: 'services-membership:modules/billing/aws/logic/billing-run.step-function.ts'
    seam: state_machine
    on_failure: Fail the execution job and invoke its configured failure consequence.
    left_inconsistent: Settled outcomes persist while unprocessed actions remain planned.
    observer: Job-step and event evidence
    provenance: observed
    source: >-
      services-membership:modules/billing/services/execution/billing-run-workflow.ts
      (header)
  - 'n': 3
    actor_or_service: Billing service
    action: >-
      Check the candidate version and settle stale or skipped actions before
      performing effects.
    anchor: >-
      services-membership:modules/billing/services/execution/execute-action.ts:prepareAction
    seam: sync
    on_failure: >-
      Roll back the action transaction; unfinished work remains eligible for the
      retry path.
    left_inconsistent: That action retains no partial database effect.
    observer: Recorded action state
    provenance: test
    source: >-
      services-membership:modules/billing/tests/integration/billing-runs.integration.spec.ts#refuses
      as stale an action whose term changed after planning
  - 'n': 4
    actor_or_service: Billing service and Commerce orders port
    action: >-
      Prepare and place renewal purchases under stable action keys, then store
      placement or refusal.
    anchor: >-
      services-membership:modules/billing/services/execution/execute-action.ts:executeOrder
    seam: sync
    on_failure: >-
      Store the placement or preparation refusal as failed; the default Commerce
      adapter refuses live orders.
    left_inconsistent: The default deployment adapter creates no renewal purchase.
    observer: Recorded action result
    provenance: unknown
    source: FND-MBR-MEM-036
  - 'n': 5
    actor_or_service: Billing service
    action: >-
      Create notice, reminder or card-warning requests and settle them within
      the local action transaction.
    anchor: >-
      services-membership:modules/billing/services/execution/billing-notices.ts:requestBillingNotice
    seam: sync
    on_failure: The action transaction fails and its database effects do not commit.
    left_inconsistent: >-
      A stored request remains unsent because its communication purpose is not
      connected.
    observer: Communication request record
    provenance: unknown
    source: FND-MBR-MEM-046
  - 'n': 6
    actor_or_service: Billing service
    action: Terminate drop candidates using the run’s effective date and reason.
    anchor: >-
      services-membership:modules/billing/services/execution/execute-action.ts:drop
    seam: sync
    on_failure: >-
      A missing reason becomes failed, a recognized membership conflict becomes
      stale, and unexpected errors abort the action and job.
    left_inconsistent: No partial local change remains.
    observer: Action outcome and published termination
    provenance: test
    source: >-
      services-membership:tests/acceptance/billing/MBR-ACC-0400.acceptance.ts#MBR-ACC-0400
  - 'n': 7
    actor_or_service: Billing run job
    action: >-
      Finish with action statistics, or conditionally return the failing job’s
      run to planned.
    anchor: >-
      services-membership:modules/billing/services/execution/billing-run-failure.ts:returnRunToPlanned
    seam: state_machine
    on_failure: >-
      The failure-task path can recover its assigned run, but no deployed
      reconciler handles missing task completion.
    left_inconsistent: A run can stay executing if failure bypasses its consequence task.
    observer: Renewal batch state
    provenance: observed
    source: >-
      services-membership:modules/billing/services/execution/billing-run-failure.ts:returnRunToPlanned
branches:
  - An automatic renewal order includes the stored payment-method reference.
waits:
  - >-
    The job processes bounded slices and retains progress between execution
    steps.
evidence:
  - >-
    services-membership at 5994c270: modules/billing/services/execution/*.ts;
    aws/logic/billing-run.step-function.ts;
    services/runs/billing-run-operations.ts
controls: [TC-AVL-002, TC-AVL-003, TC-AVL-004, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-005, TC-AZ-006, TC-CHG-001, TC-CHG-002, TC-CHG-003, TC-CHG-004, TC-CRY-001, TC-CRY-002, TC-CRY-003, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-DAT-007, TC-IAM-001, TC-IAM-002, TC-IAM-004, TC-IAM-005, TC-IAM-006, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, 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, TC-SEC-001, TC-SEC-004, TC-TEN-001, TC-TEN-002, TC-TEN-003]
---

# Execute a billing run on the durable jobs engine

## What It Does

Durable execution processes reviewed renewal actions in bounded slices. Orders cross the Commerce port; notices and drops commit locally with their result.

## The Flow

```mermaid
flowchart TD
  H1["Create the execution job and mark the run executing together, then request job startup after commit"]
  H2["Process planned actions in slices, repeating the execution step while work remains"]
  H1 --> H2
  H3["Check the candidate version and settle stale or skipped actions before performing effects"]
  H2 --> H3
  H4["Prepare and place renewal purchases under stable action keys, then store placement or refusal"]
  H3 --> H4
  H5["Create notice, reminder or card-warning requests and settle them within the local action transaction"]
  H4 --> H5
  H6["Terminate drop candidates using the run’s effective date and reason"]
  H5 --> H6
  H7["Finish with action statistics, or conditionally return the failing job’s run to planned"]
  H6 --> H7
```

## When Something Fails

The failure consequence returns only the run still assigned to that failed job to planned. No deployed reconciler heals a job that never starts or bypasses the consequence. Refusing Commerce placement settles order actions failed, and unconnected communication purposes store requests without sending. Organization recipients and actual card-expiry checks remain incomplete.