# BillingRunBatchStatusDto

A model the API reference uses in a request or a response. The operation pages link every field typed as this model here.

Live status of an admin all-resellers billing fan-out batch. Returned by
`TriggerAllResellersAsync` (immediately, before the run
finishes) and by `GetActiveOrLatestBatchAsync` (the grid's
Refresh/poll surface). When the batch is terminal, the counts + `outcomes` carry
the completion summary the UI renders.

## Fields
- `batchId` (string(uuid)): Batch document id (the tracking id returned at trigger time).
- `orchestrationInstanceId` (string): Identifier of the background job processing the batch. Null until processing has started. (nullable)
- `periodKey` (string): Billing period key (yyyyMM) the batch is running for. (nullable)
- `isDryRun` (boolean): True when charges are previewed without generating invoices/charges.
- `status` ([MerchantBillingRunBatchStatus](https://devportal.demo.winkpg.io/docs/api/models/MerchantBillingRunBatchStatus.md)): Current batch status.
  Values:
  - `Pending`: Batch created and the workflow has been started but discovery has not run yet.
  - `Running`: The fan-out workflow is running per-reseller billing runs.
  - `Completed`: Every reseller that ran completed without a failed reseller run.
  - `PartiallyCompleted`: At least one reseller ran successfully and at least one reseller run failed.
  - `Failed`: No reseller ran successfully and at least one reseller run failed.
  - `Cleared`: An admin force-cleared the batch from the Billing Runs page. A terminal, non-failure state distinct from Failed: it records a deliberate operator action (releasing a stuck or stale batch) rather than a run that errored. Like every other terminal status it is reclaimable by the next fan-out's lock-recovery, and is never treated as in-progress.
- `triggeredByUserId` (string(uuid)): User that triggered the batch. (nullable)
- `triggeredByUserName` (string): Display name of the user that triggered the batch. (nullable)
- `startedAt` (string(date-time)): When the fan-out workflow started processing. (nullable)
- `completedAt` (string(date-time)): When the batch reached a terminal status. (nullable)
- `clearedByUserName` (string): Display name of the admin that force-cleared the batch, when              `status` is `Cleared`. (nullable)
- `resellersConsidered` (integer(int32))
- `resellersRun` (integer(int32))
- `resellersSkipped` (integer(int32))
- `resellersFailed` (integer(int32))
- `totalMerchantsBilled` (integer(int32))
- `totalMerchantsFailed` (integer(int32))
- `outcomes` (array<[BillingRunResellerOutcomeDto](https://devportal.demo.winkpg.io/docs/api/models/BillingRunResellerOutcomeDto.md)>): Per-reseller outcomes (populated once the batch completes). (nullable)
  Fields of each item:
  - `resellerId` (string(uuid))
  - `resellerName` (string): Display name of the reseller, when resolvable (admin fan-out only). (nullable)
  - `billingRunId` (string(uuid)): The created run's id, when a run executed (null for skipped resellers). (nullable)
  - `outcome` ([BillingRunResellerOutcome](https://devportal.demo.winkpg.io/docs/api/models/BillingRunResellerOutcome.md)): Classifies how a single reseller fared within an admin billing-run batch. Lives in  Domain.Shared so the Domain aggregate (`MerchantBillingRunBatch`'s embedded  outcome) and the Application.Contracts DTOs can both reference it without a layer violation.
    Values:
    - `Completed`: A run executed for the reseller (may include per-merchant failures within it).
    - `SkippedNoBillableMerchants`: No merchants were assigned to a price plan for the period: no run was created.
    - `SkippedAlreadyRun`: A completed (non-dry) run already exists for this reseller and period.
    - `SkippedRunInProgress`: A run is already in progress for this reseller.
    - `Failed`: The reseller's run failed before completion (or failed to enqueue).
    - `Scheduled`: The reseller's run was accepted and queued as a background job. Merchants are billed asynchronously; the run's final status (Completed, PartiallyCompleted or Failed) appears on the run once processing finishes. An all-resellers batch reports progress through the batch status instead.
    - `SkippedMerchantBillingDisabled`: The reseller has the "Merchant Billing" master switch (ResellerFeatures.MerchantBilling) turned off, so no run was created and no invoices were generated for its merchants.
  - `successCount` (integer(int32)): Merchants successfully billed in this reseller's run.
  - `failureCount` (integer(int32)): Merchants that failed in this reseller's run.
  - `totalBilledAmount` (number(double)): Total amount billed in this reseller's run.
- `isInProgress` (boolean): True while the batch is non-terminal (Pending or Running). (read only)

## See also

- [All documentation](https://devportal.demo.winkpg.io/llms.txt): the machine-readable index of every public page on this site.