Receitas de Policies

Guias práticos passo a passo para configurações comuns de policies. Cada receita descreve um cenário, percorre a configuração e explica o resultado esperado.

Para a referência completa de campos, consulte Policies Disponíveis. Para saber onde fazer alterações, consulte Configurando Policies.

---

Receita 1: Definir período de carência de 30 dias para todos os entitlements de Plugin

Cenário

Você quer que entitlements de plugin aguardem 30 dias no estado "expirado" antes de serem cancelados automaticamente, em vez dos atuais 14 dias. Isso dá aos clientes mais tempo para renovar licenças de plugin vencidas.

Configuração

Nível: Entitlement Class (PLG)

Policy: Cancellation Policy

Arquivo: docs/commerce/policies/class-plg.yaml

Alteração:

cancellation:
  expired_to_cancelled_days: 30    # era: 14

O que acontece

• Todos os entitlements PLG que expirarem agora permanecerão no estado "expirado" por 30 dias.
• Durante esses 30 dias, o cliente ainda pode renovar e reativar.
• Após 30 dias sem renovação, o entitlement é movido para "cancelado" automaticamente.
• Isso afeta apenas entitlements PLG. ENV, SVC e outras classes mantêm seus próprios valores.

Verificação

Após a sincronização, verifique qualquer entitlement PLG expirado. A data de cancelamento agendada deve ser 30 dias após a data de expiração, e não 14.

---

Receita 2: Desabilitar renovação automática para uma organização específica

Cenário

A organização "University ABC" quer lidar com renovações manualmente pelo setor de compras. Eles não querem cobranças automáticas.

Configuração

Nível: Organização

Policy: Renewal Policy

Local: WP Admin > Organizations > University ABC > Editar > Aba Policies (interface planejada)

Sobrescrita:

Campo	Valor
auto_renew	false

Até que a interface de admin esteja disponível, isso pode ser definido como metadado da organização com chave policy.renewal.auto_renew e valor false.

O que acontece

• Todos os entitlements da University ABC NÃO serão renovados automaticamente.
• E-mails de lembrete de renovação continuarão sendo enviados (conforme a Notification Policy) para que o setor de compras saiba quando agir.
• Se eles não renovarem manualmente antes da expiração, o entitlement expirará e seguirá o cronograma da Cancellation Policy.
• Todas as outras organizações continuam com renovação automática conforme configurado globalmente.

Verificação

Verifique um entitlement ativo da University ABC. O comportamento de renovação deve mostrar "Manual" em vez de "Automático". O entitlement não deve acionar uma cobrança de renovação antes da expiração.

---

Receita 3: Configurar tempos de resposta de SLA para entitlements de Serviço

Cenário

Seus contratos de serviço (classe SVC) devem usar por padrão o tier de SLA Priority com horário de suporte estendido, e o escalonamento deve acionar mais cedo (a 70% do tempo de SLA) porque clientes de serviço têm expectativas mais altas.

Configuração

Nível: Entitlement Class (SVC)

Policy: SLA Policy

Arquivo: docs/commerce/policies/class-svc.yaml

Valores:

sla:
  sla_level: priority
  response_time:
    priority:
      P1: "4h"
      P2: "8h"
      P3: "1d"
      P4: "2d"
      P5: "3d"
  resolution_time:
    priority:
      P1: "1d"
      P2: "2d"
      P3: "3d"
      P4: "5d"
      P5: "7d"
  support_hours: extended
  escalation_after_pct: 70

O que acontece

• Todas as solicitações de serviço criadas contra entitlements SVC usarão as metas de SLA Priority.
• Um ticket P1 terá meta de primeira resposta de 4 horas e meta de resolução de 1 dia.
• O horário de suporte é estendido (8:00-22:00 BRT, seg-sex) em vez do horário comercial padrão.
• O escalonamento é acionado a 70% do prazo de SLA em vez dos 80% globais.
• Entitlements PLG e ENV não são afetados; mantêm suas próprias configurações de SLA.

Verificação

Crie uma solicitação de serviço de teste contra um entitlement SVC. Confirme que as metas de SLA exibidas correspondem aos valores do tier Priority e que o horário de suporte aparece como "Estendido".

---

Receita 4: Configurar período de trial para o produto de hospedagem Campus EAD

Cenário

Você quer oferecer um trial gratuito de 14 dias para o produto de hospedagem Campus EAD (classe ENV). Para prevenir abuso dos recursos de provisionamento em nuvem, um cartão de crédito é exigido para iniciar o trial. Cada organização pode fazer trial apenas uma vez.

Configuração

Nível: Entitlement Class (ENV)

Policy: Trial Policy

Arquivo: docs/commerce/policies/class-env.yaml

Valores:

trial:
  enabled: true
  duration_days: 14
  auto_convert: true
  require_payment_method: true
  max_trials_per_org: 1
  extend_allowed: false
  notification_days_before_end:
    - 3
    - 1

O que acontece

• Clientes podem iniciar um trial de 14 dias para qualquer produto ENV.
• Um método de pagamento válido é exigido antes do início do trial.
• Ao fim do trial, o entitlement é convertido automaticamente para uma assinatura paga (o cartão é cobrado).
• Cada organização pode iniciar apenas um trial — se tentar novamente, o sistema rejeita.
• Notificações são enviadas 3 dias e 1 dia antes do fim do trial.
• O admin não pode estender trials (defina extend_allowed: true se quiser permitir isso).

Verificação

Tente iniciar um trial para um produto ENV. Confirme que:

1. Um método de pagamento é exigido antes da ativação do trial.
2. A duração do trial exibe 14 dias.
3. Uma segunda tentativa de trial para a mesma organização é rejeitada.
4. E-mails de notificação são enviados 3 dias e 1 dia antes do fim do trial.

---

Receita 5: Lidar com recuperação de pagamento com escalonamento

Cenário

Você quer um processo de recuperação de pagamento firme, mas justo:

1. Não suspender na primeira falha de pagamento — aguardar até que todas as retentativas do Stripe se esgotem.
2. Uma vez suspenso, dar ao cliente 30 dias para corrigir o pagamento.
3. Reativar automaticamente no momento em que o pagamento for bem-sucedido.
4. Para um cliente específico (Org "Gamma Corp") com processos internos lentos, estender a janela de suspensão para 60 dias.

Configuração

Etapa 1: Padrões globais (já em global.yaml)

payment_recovery:
  trigger: retry_exhausted
  suspended_to_cancelled_days: 30
  auto_reactivate_on_payment: true

Etapa 2: Sobrescrita de organização para Gamma Corp

Nível: Organização

Local: WP Admin > Organizations > Gamma Corp > Editar > Aba Policies (interface planejada)

Campo	Valor
suspended_to_cancelled_days	60

O que acontece

• Para a maioria dos clientes: o Stripe retenta o pagamento (tipicamente 3-4 tentativas ao longo de ~7 dias). Se todas as retentativas falharem, o entitlement é suspenso. 30 dias depois, se ainda não pago, o entitlement é cancelado automaticamente.
• Para Gamma Corp: mesmo processo, mas eles recebem 60 dias em estado suspenso em vez de 30.
• Em ambos os casos, se o cliente atualizar o método de pagamento e a cobrança for bem-sucedida, o entitlement é imediatamente reativado sem intervenção do admin.

Verificação

Para um cliente padrão: acione uma falha de pagamento no ambiente de teste. Após as retentativas se esgotarem, confirme que o entitlement vai para "suspenso". Confirme que o cancelamento agendado é 30 dias depois.

Para Gamma Corp: mesmo teste, mas confirme que o cancelamento agendado é 60 dias após a suspensão.

---

Receita 6: Configurar termos de reembolso generosos para produtos Plugin

Cenário

Seus produtos de plugin devem oferecer uma janela de reembolso de 30 dias com reembolsos automáticos para compras abaixo de R$500 BRL ou $100 USD. Valores acima exigem aprovação do admin. Um reembolso total cancela o entitlement.

Configuração

Nível: Entitlement Class (PLG)

Policy: Refund Policy

Arquivo: docs/commerce/policies/class-plg.yaml

Valores:

refund:
  refund_window_days: 30
  auto_refund: true
  auto_refund_max:
    brl: "500.00"
    usd: "100.00"

Outros campos (partial_allowed, approval_required, cancel_entitlement, credits_on_refund) herdam dos padrões globais.

O que acontece

• Um cliente que comprou um plugin nos últimos 30 dias pode solicitar reembolso.
• Se o valor da compra for R$500 ou menos (BRL) ou $100 ou menos (USD), o reembolso é processado automaticamente sem envolvimento do admin.
• Se o valor exceder o limite, a solicitação de reembolso é enfileirada para aprovação do admin.
• Após um reembolso total, o entitlement é cancelado automaticamente (herdado cancel_entitlement: true).
• Reembolsos parciais são permitidos (herdado partial_allowed: true), calculados proporcionalmente ao uso.

Verificação

Teste com uma compra abaixo do limite de reembolso automático. Solicite um reembolso dentro de 30 dias. Confirme que é aprovado automaticamente e que o entitlement vai para "cancelado". Teste novamente com um valor acima do limite e confirme que exige aprovação do admin.

---

Receita 7: Prevenir abuso de mudança de tier em contratos de serviço

Cenário

Você quer impedir que clientes troquem rapidamente entre tiers de serviço em contratos anuais. Downgrades devem exigir aprovação do admin, deve haver um cooldown de 90 dias entre mudanças, e as mudanças de tier devem entrar em vigor no próximo ciclo de cobrança (não imediatamente).

Configuração

Nível: Entitlement Class (SVC)

Policy: Tier Change Policy

Arquivo: docs/commerce/policies/class-svc.yaml

Valores:

tier_change:
  effect: next_cycle
  downgrade_requires_approval: admin
  cooldown_days: 90
  credit_behavior: next_cycle

O que acontece

• Quando um cliente SVC solicita um upgrade, ele é aceito mas entra em vigor no próximo ciclo de cobrança, não imediatamente.
• Quando um cliente SVC solicita um downgrade, deve ser aprovado por um admin antes de prosseguir.
• Após qualquer mudança de tier (para cima ou para baixo), o cliente deve aguardar 90 dias antes de fazer outra alteração.
• As alocações de crédito são ajustadas no próximo ciclo de cobrança, não no momento da mudança.
• Entitlements PLG e ENV não são afetados — suas mudanças de tier permanecem imediatas e sem cooldown (padrões globais).

Verificação

Tente um downgrade em um entitlement SVC. Confirme que fica retido para aprovação do admin. Após a aprovação, confirme que a mudança está agendada para o próximo ciclo de cobrança. Tente outra mudança de tier dentro de 90 dias e confirme que é rejeitada com uma mensagem de cooldown.

---

Receita 8: Configurar avisos de expiração antecipados para ambientes de hospedagem

Cenário

Ambientes de hospedagem (classe ENV) ficarem offline é um problema crítico para os clientes. Você quer enviar avisos de expiração mais cedo e com maior frequência do que o padrão global.

Configuração

Nível: Entitlement Class (ENV)

Policy: Notification Policy

Arquivo: docs/commerce/policies/class-env.yaml

Valores:

notification:
  expiry_warning_days:
    - 60
    - 30
    - 7
    - 1

O que acontece

• Entitlements ENV enviarão avisos de expiração 60, 30, 7 e 1 dia antes da expiração.
• O padrão global ([30, 7, 1]) é completamente substituído — não mesclado com — a sobrescrita da classe.
• Entitlements PLG e SVC mantêm seus próprios cronogramas de notificação.
• Todas as outras configurações de notificação (canais, eventos, opt-out) são herdadas dos padrões globais, a menos que também sejam sobrescritas.

Verificação

Verifique um entitlement ENV ativo com data de expiração daqui a 65 dias. Ao longo dos próximos dias, confirme que e-mails de aviso são enviados nas marcas de 60, 30, 7 e 1 dia.

---

Resumo

Receita	Nível	Policy	Alteração principal
1	Classe (PLG)	Cancellation	30 dias expirado-para-cancelado
2	Organização	Renewal	Desabilitar renovação automática
3	Classe (SVC)	SLA	Tier Priority, horário estendido
4	Classe (ENV)	Trial	Trial de 14 dias, cartão obrigatório
5	Global + Org	Payment Recovery	30d padrão, 60d para um cliente
6	Classe (PLG)	Refund	Reembolso automático até R$500/$100
7	Classe (SVC)	Tier Change	90d cooldown, aprovação admin
8	Classe (ENV)	Notification	Avisos de expiração antecipados

Próximos passos

• Visão Geral do Policy Engine — a visão macro
• Policies Disponíveis — referência completa de campos
• Hierarquia de Policies — como funciona a resolução de sobrescritas
• Configurando Policies — onde encontrar as configurações