> ## 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.

# Programs

> Programas de afiliados e seus sub-recursos: tiers, regras de comissão e termos.

`repass.programs` gerencia [programas](/docs/conceitos/programas-e-regras) (moeda, modelo e janela de [atribuição](/docs/conceitos/atribuicao), hold de comissão e modo de aprovação), além dos sub-recursos `tiers` (cada um com seu próprio `commissionRules`), `commissionRules` (a regra padrão do programa) e `terms`.

## Programa

```ts theme={null}
// Criar
const program = await repass.programs.create({
  name: "Programa de Indicações",
  attributionModel: "last_click",
  approvalMode: "manual",
}); // → Program

// Buscar
await repass.programs.retrieve("prog_…"); // → Program

// Listar (RepassPage, filtro opcional por status)
await repass.programs.list({ status: "active" }); // → RepassPage<Program>

// Atualizar (parcial)
await repass.programs.update("prog_…", { holdDays: 15 }); // → Program
```

### Ações de estado

```ts theme={null}
await repass.programs.pause("prog_…");    // → Program (active → paused)
await repass.programs.activate("prog_…"); // → Program (paused → active)
await repass.programs.archive("prog_…");  // → Program (encerra permanentemente)
```

## Tiers

`repass.programs.tiers`: lista **ordenada** de tiers, geridos **individualmente** (criar, renomear, reposicionar, reordenar e arquivar). Cada tier tem seu **próprio histórico** de regras de comissão (sub-recurso `commissionRules`). `ProgramTier` traz `archivedAt` (soft-delete; `null` quando ativo) e **não** carrega mais referência direta a uma regra. Os métodos `list`/`reorder` retornam um array (não paginado).

```ts theme={null}
await repass.programs.tiers.list("prog_…"); // → ProgramTier[] (apenas ativos, por posição)

// Criar (posição no fim se omitida)
await repass.programs.tiers.create("prog_…", { name: "Ouro" }); // → ProgramTier

// Renomear e/ou reposicionar um tier ativo
await repass.programs.tiers.update("prog_…", "tier_…", { name: "Platina" }); // → ProgramTier

// Reordenar (informe os IDs dos tiers ativos na nova ordem)
await repass.programs.tiers.reorder("prog_…", {
  tierIds: ["tier_ouro", "tier_prata"],
}); // → ProgramTier[]

// Arquivar (soft-delete, idempotente)
await repass.programs.tiers.archive("prog_…", "tier_…"); // → ProgramTier (com archivedAt)
```

### Regras de comissão do tier

`repass.programs.tiers.commissionRules`: cada tier tem seu próprio histórico [versionado e imutável](/docs/conceitos/comissoes) de regras, independente do padrão do programa. Enquanto o tier não publica uma regra própria, ele cai na regra padrão do programa (ver [precedência](/docs/conceitos/programas-e-regras)).

```ts theme={null}
// Publicar nova versão da regra do tier (percentage | fixed | tiered)
await repass.programs.tiers.commissionRules.publish("prog_…", "tier_…", {
  type: "percentage",
  percentage: 25, // 25%
}); // → CommissionRule (com programTierId === "tier_…")

await repass.programs.tiers.commissionRules.list("prog_…", "tier_…");    // → CommissionRule[] (todas as versões do tier)
await repass.programs.tiers.commissionRules.current("prog_…", "tier_…"); // → CommissionRule (versão vigente do tier; 404 se ainda não há regra própria)
```

## Regras de comissão (padrão do programa)

`repass.programs.commissionRules`: regra **padrão** do programa, [versionada e imutável](/docs/conceitos/comissoes); cada alteração publica uma nova versão. É o dono `programTierId === null`: o fallback de qualquer afiliado sem regra custom e sem regra de tier própria.

```ts theme={null}
// Criar nova versão (percentage | fixed | tiered)
await repass.programs.commissionRules.create("prog_…", {
  type: "percentage",
  percentage: 10, // 10%
  recurrence: { kind: "one_time" },
}); // → CommissionRule (com programTierId === null)

await repass.programs.commissionRules.list("prog_…");        // → CommissionRule[] (todas as versões)
await repass.programs.commissionRules.current("prog_…");     // → CommissionRule (versão vigente)
await repass.programs.commissionRules.retrieve("prog_…", "cmrl_…"); // → CommissionRule (versão específica)
```

## Termos

`repass.programs.terms`: versões dos [termos](/docs/conceitos/termos) do programa.

```ts theme={null}
await repass.programs.terms.list("prog_…"); // → ProgramTerms[] (versões publicadas)
await repass.programs.terms.publish("prog_…", {
  content: "# Termos do Programa…",
  requireReacceptance: true,
}); // → ProgramTerms
```

<Note>
  Para o schema completo de cada corpo (defaults de programa, formato de `recurrence`, tiers etc.) e os campos dos objetos retornados (ex.: `Program`), consulte a [Referência da API](/docs/convencoes/ids-e-recursos). As regras de negócio de programas e comissões estão em [Programas e regras](/docs/conceitos/programas-e-regras) e [Comissões](/docs/conceitos/comissoes).
</Note>