> ## Documentation Index
> Fetch the complete documentation index at: https://userepass.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Payouts (CLI)

> Comandos de ciclos de pagamento: prévia, execução, retentativa, cancelamento, recibos e relatório contábil.

O grupo `payouts` gerencia os ciclos de [payout](/docs/conceitos/payouts), agregando comissões aprovadas em pagamentos por afiliado, com prévia, execução, retentativa e recibos. Lotes de fechamento (`payout-batches`) ficam em outra página.

## Consulta

```bash theme={null}
# Listar (paginado, com filtros)
repass payouts list --status completed --method pix --json

# Buscar
repass payouts get pay_xxx --json
```

`payouts list` é paginado. Veja [Paginação](/docs/cli/paginacao) para `--all` e cursores.

## Prévia e execução

`preview` e `run` têm efeito pesado sobre o ciclo: ambos são `sensitive`.

```bash theme={null}
# Simula o fechamento (elegíveis, bloqueados e totais), sem agendar nada
repass payouts preview --program-id prog_xxx --json
```

```json repass payouts preview --json theme={null}
{
  "eligible": [{ "affiliateId": "aff_xxx", "amountCents": 45000, "destination": "maria@exemplo.com" }],
  "blocked": [],
  "totals": { "eligibleCents": 45000, "blockedCents": 0 }
}
```

<Warning>
  `payouts preview` é `sensitive` mesmo não escrevendo nada: ele roda a mesma simulação pesada usada pelo fechamento (elegibilidade, bloqueios e totais) sobre dados de produção. Em terminal interativo pede confirmação; fora de TTY exige `--yes` (veja [Convenções](/docs/cli/convencoes#modelo-de-risco)).
</Warning>

`payouts run` é **dry-run por padrão**: sem `--live`, ele simula o fechamento sem agendar nada de verdade, igual a `preview`. Só use `--live` depois de revisar o dry-run com o usuário:

```bash theme={null}
# Dry-run (sem --live): mostra o que aconteceria, não agenda nada
repass payouts run --program-id prog_xxx

# Executa de verdade
repass payouts run --program-id prog_xxx --live --yes
```

<Warning>
  `payouts run` é `sensitive`: sem `--live` é sempre dry-run (seguro de repetir); **com `--live` agenda payouts de verdade**. Rode `payouts preview` (ou `payouts run` sem `--live`) primeiro, mostre o resultado ao usuário e só use `--live` com aprovação explícita. Em terminal interativo pede confirmação; fora de TTY exige `--yes` (veja [Convenções](/docs/cli/convencoes#modelo-de-risco)).
</Warning>

## Relatório contábil

`accounting-report` retorna a visão contábil dos payouts liquidados num período (por data de pagamento). `--from`/`--to` são obrigatórios.

```bash theme={null}
repass payouts accounting-report --from 2026-06-01T00:00:00Z --to 2026-07-01T00:00:00Z --json
```

## Retentativa, cancelamento e recibos

```bash theme={null}
repass payouts retry pay_xxx     # reprocessa um payout que falhou
repass payouts cancel pay_xxx    # cancela (comissões voltam a aprovadas não pagas)
repass payouts receipt pay_xxx   # URL do comprovante no provedor
```

<Warning>
  `payouts cancel` é `destructive`. As comissões voltam a um estado anterior, mas o payout em si não "renasce". Rode `payouts get pay_xxx` antes para ver status/valor. Em terminal interativo pede confirmação; fora de TTY exige `--yes` (veja [Convenções](/docs/cli/convencoes#modelo-de-risco)).

  ```bash theme={null}
  repass payouts cancel pay_xxx --yes
  ```
</Warning>

<Note>
  Para o schema completo de cada corpo (filtros do ciclo, formato de `totals`, status e métodos) e os campos de cada objeto retornado, consulte a página SDK equivalente ([Payouts](/docs/sdk/recursos/payouts)) e a [Referência da API](/docs/convencoes/ids-e-recursos). As regras de negócio estão em [Payouts](/docs/conceitos/payouts). Lotes de fechamento ficam em [payout-batches](/docs/cli/recursos/payout-batches).
</Note>