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

# Triggers de automação

> Quando cada gatilho dispara, quais dados vêm junto e para que usar.

Use exatamente um destes valores em `trigger_event`. Qualquer outro nome é rejeitado ao salvar.

Não existem `order.shipped`, `order.created` nem `order.paid`. Para envio use `tracking_code_updated`. Para compra paga use `payment.confirmed`.

A automação só corre se estiver **ativa** e pertencer à **mesma loja** do evento.

## Catálogo

| Trigger                          | Dispara quando                                                         | Casos comuns                              | Pode repetir?                                                                         |
| -------------------------------- | ---------------------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------- |
| `pix.generated`                  | Uma cobrança PIX é gerada e os dados de pagamento já estão disponíveis | Enviar copia-e-cola, lembrar PIX pendente | No mesmo pedido, a plataforma evita duplicar                                          |
| `boleto.generated`               | Um boleto é gerado e os dados de pagamento já estão disponíveis        | Enviar linha digitável ou link do boleto  | No mesmo pedido, evita duplicar                                                       |
| `payment.confirmed`              | O pagamento é confirmado                                               | Obrigado, pós-compra, instruções          | Pode chegar por mais de um caminho de confirmação; a plataforma agrupa o mesmo pedido |
| `payment.failed`                 | O pagamento é recusado ou a cobrança falha                             | Avisar recusa, pedir outro meio           | Pode ocorrer de novo em nova tentativa                                                |
| `cart.abandoned`                 | Um checkout elegível é considerado abandonado                          | Recuperar carrinho, lembrar checkout      | Em geral **uma vez** por lead/checkout                                                |
| `lead.created`                   | Um lead **novo** é capturado                                           | Boas-vindas, nutrição inicial             | Uma vez por lead                                                                      |
| `tracking_code_updated`          | Código, URL ou status de rastreio muda                                 | Avisar envio, link de rastreio            | Sim, quando o rastreio muda de verdade                                                |
| `email.received`                 | A caixa da loja recebe um e-mail                                       | Encaminhar ou responder o contato         | Uma vez por e-mail recebido                                                           |
| `subscription.payment.confirmed` | Cobrança recorrente paga                                               | Recibo do ciclo                           | Por ciclo/pedido                                                                      |
| `subscription.payment.failed`    | Cobrança recorrente recusada                                           | Pedir atualização de cartão               | Por ciclo/pedido                                                                      |
| `subscription.reminder`          | Lembrete antes do vencimento da assinatura                             | Avisar cobrança próxima                   | Conforme os dias configurados na assinatura                                           |
| `subscription.overdue`           | Lembrete de assinatura em atraso                                       | Cobrança vencida                          | Conforme os dias configurados                                                         |
| `subscription.suspended`         | Assinatura é suspensa                                                  | Avisar interrupção                        | Em geral no momento da suspensão                                                      |

## Cada gatilho

### `pix.generated`

Disparado quando uma cobrança PIX é criada com sucesso e os dados necessários para pagar já estão disponíveis.

**Contextos no catálogo de metatags:** customer, order, payment/PIX, lead, store, shipping, browser.

**Casos comuns:** envio do copia-e-cola, recuperação de PIX pendente, QR no e-mail.

**Observações:** use `{{order.pix_code}}` e `{{order.url_pix_gerado}}`. `{{order.pix_qr_code}}` é HTML para e-mail.

Renovação de assinatura paga no checkout **não** gera este evento de PIX/boleto de primeira compra.

### `boleto.generated`

Disparado quando um boleto é emitido e os dados de pagamento já estão disponíveis.

**Contextos no catálogo:** customer, order (inclui boleto), lead, store, shipping, browser. Sem metatags de PIX.

**Casos comuns:** enviar linha digitável (`{{order.boleto_digitable_line}}`), código de barras (`{{order.boleto_barcode}}`) ou link (`{{order.url_boleto_gerado}}` / `{{order.boleto_url}}`).

### `payment.confirmed`

Disparado quando um pagamento é confirmado.

**Disponível para:** pedidos pagos, comunicação pós-compra, fluxos transacionais.

**Contextos no catálogo:** customer, order, lead, store, shipping, browser.

**Casos comuns:** confirmação, instruções pós-compra, início de pós-venda.

**Observações:** o evento pode originar-se de cartão à vista, PIX compensado, boleto pago ou confirmação posterior. Isso é transparente na configuração. Metatags de PIX (`{{order.pix_code}}`) **não** entram neste gatilho.

### `payment.failed`

Disparado quando o pagamento é recusado ou a cobrança não conclui.

**Contextos no catálogo:** customer, order, lead, store, shipping, browser. Sem PIX e sem chaves de boleto.

**Casos comuns:** avisar recusa (`{{customer.name}}`, `{{order.total}}`) e sugerir outro meio.

### `cart.abandoned`

Disparado quando um carrinho/checkout elegível é identificado como abandonado.

**Contextos no catálogo:** customer, lead, cart, checkout, order (dados do checkout), store.

**Casos comuns:** recuperação de carrinho, lembrete, retomada do checkout (`{{cart.url_checkout}}`).

**Observações:** exige contato válido segundo as regras da loja (nome + e-mail ou nome + telefone). Não dispara se o lead já concluiu ou converteu, nem se o abandono já foi notificado. Sem dados de checkout/lead suficientes, a automação não envia.

### `lead.created`

Disparado quando um lead **novo** entra na loja (primeira captura). Visitas seguintes do mesmo lead **não** disparam de novo.

**Contextos no catálogo:** customer (parcial), lead, order (limitado).

**Casos comuns:** boas-vindas e início de nutrição.

**Observações:** o evento de criação pode não trazer nome/e-mail/telefone preenchidos ainda. Prefira `{{lead.*}}` e trate vazios.

### `tracking_code_updated`

Disparado quando o código, a URL ou o status de rastreio de um pedido muda.

**Contextos no catálogo:** customer, order, store, shipping, tracking.

**Casos comuns:** “seu pedido saiu”, link de rastreio.

**Observações:** não dispara se o código estiver vazio ou se nada mudou. Status em conditions: `posted`, `in_transit`, `out_for_delivery`, `delivered`, `failed`, `returned`, `unknown`.

### `email.received`

Disparado quando a caixa de e-mail da loja recebe uma mensagem.

**Contextos no catálogo:** customer, inbound (`{{inbound.subject}}`, `{{inbound.from}}`, `{{inbound.text}}`, `{{inbound.to}}`).

**Casos comuns:** avisar a equipe ou responder o cliente em outro canal.

### `subscription.payment.confirmed`

Disparado quando a cobrança de um ciclo de assinatura é paga.

**Contextos no catálogo:** subscription (`{{subscription.id}}`, `{{subscription.total}}`, `{{subscription.portalUrl}}`, …).

**Casos comuns:** recibo do ciclo, acesso liberado.

### `subscription.payment.failed`

Disparado quando a cobrança recorrente é recusada.

**Contextos no catálogo:** subscription, incluindo `{{subscription.failureReason}}` e `{{subscription.portalUrl}}`.

**Casos comuns:** pedir atualização de cartão.

### `subscription.reminder`

Disparado nos dias de lembrete **antes** do vencimento, conforme a configuração da assinatura.

**Contextos no catálogo:** subscription, incluindo `{{subscription.daysUntilDue}}`.

### `subscription.overdue`

Disparado nos dias de lembrete **depois** do vencimento, se a cobrança segue em aberto.

**Contextos no catálogo:** subscription, incluindo `{{subscription.daysOverdue}}`.

### `subscription.suspended`

Disparado quando a assinatura é suspensa.

**Contextos no catálogo:** subscription.

## Quando a automação não corre

* `active` está `false`.
* O gatilho do fluxo é outro.
* O evento é de **outra loja**.
* Proteção contra duplicidade: o mesmo pagamento, lead ou e-mail já disparou essa automação.
* `cart.abandoned` sem contato elegível, checkout já concluído, ou abandono já notificado.
* `lead.created` em lead que já existia.
* `tracking_code_updated` sem mudança real de rastreio.

Consulte as metatags oficiais por gatilho em `GET /api/v1/automation/metatags?triggerType=...`, na [página de metatags](/automations-metatags) ou na [matriz gatilho × contexto](/automations-trigger-context).