## Overview

The **e-commerce lifecycle** connects external platforms — **Kiwify, Hotmart, Nuvemshop and Shopify**
— so that sales events arrive inside your support. When something happens on the external platform
(abandoned cart, PIX/boleto generated, purchase approved, declined or refunded), ConversaLabs receives
the **webhook**, normalizes the event, and shows a **card in the customer's conversation**, with
payment data when available.

With this, you recover sales without switching tools: the team sees the purchase stage right in the
conversation and can trigger automatic **Follow-ups** to win back anyone who didn't complete.

## Prerequisites

- The **Catalog & Commerce** module enabled and permission to configure commerce sources.
- Access to the external platform (Kiwify, Hotmart, Nuvemshop or Shopify) to set up the webhook.
- For automatic recovery: the **Follow-ups** module configured with event-triggered sequences.

## Step by step

1. In the **Catalog & Commerce** area, create a **commerce source** for the desired platform.
2. Copy the complete **webhook URL** generated for that source. It includes both the account and the
   source; do not remove either segment. Also configure the **verification secret**. On Kiwify,
   automatic registration can generate and save the token; on Hotmart, enter the application's Hottok.
3. Paste the URL into the external platform's panel (or use **automatic registration** when available,
   for example on Kiwify and Nuvemshop).
4. Make a test sale (or a test cart) to confirm the event arrives.
5. See the **event card** appear in the customer's conversation, with items, amounts and the
   payment link/data depending on the stage.
6. Set up **event-triggered Follow-ups** (for example, "abandoned cart") to recover the sale
   automatically.

## Settings & options

### Payment and card sending are separate states

In the conversation's **Commerce** panel, the title describes the recorded commerce event and
**Card sending** describes only the send attempt for that card. **Payment confirmed** together
with **Not attempted** does not mean payment is pending: the financial confirmation is recorded,
but this Commerce card has no recorded send attempt yet. Other payment messages may already be
in the conversation.

Use **View card** to open the linked message when available, or **Open conversation** to review
the history. **Send confirmation** or **Resend confirmation** opens a dialog before sending; you
can cancel. This action does not create a charge or change the financial confirmation. Resending
an existing card requires your explicit confirmation. Without a linked conversation, the server
looks for an existing conversation with the contact; this panel does not open a new one.

A card recorded in the conversation does not prove customer receipt: check the message and
channel status too. Failures, refused sends and unconfirmed responses are not presented as
success. Messages and boletos sent before settlement remain in the history; their presence does
not make a confirmed payment pending. Do not use a receipt image to replace the financial status
recorded by the gateway or an authorized operator.

- **Commerce source**: one per platform, with its own webhook URL and verification secret.
- **Automatic webhook registration**: available on some platforms (e.g. Kiwify and Nuvemshop); on the
  others, setup is manual in the platform's own panel.
- **Event card**: shows the purchase stage and, when the platform exposes it, PIX/boleto data and the
  checkout link.
- **Commerce variables**: data from the latest event is available for use in Follow-up messages
  (payment link, amount, PIX/boleto code, etc.).

### Choose which events to receive

When you edit the source under **Catalog → Sync sources → edit the source**, the **Events** section lists
the events that platform sends and lets you map **each one** to a lifecycle stage — or set it to **Off
(ignore)** to drop it entirely.

Every enabled event flows through the rest of the platform: **automations, flows, webhooks, Follow-up and
the CRM**. The mapping is what decides **which stage** it becomes.

A prominent **Abandoned cart recovery** switch turns the platform's abandoned-cart event on and off — it
is what drives the recovery cadence in Follow-up (the `commerce.cart_abandoned` trigger).

Available for:

| Source | Events you map |
|---|---|
| **Hotmart** | purchase, cart, subscription and members-area events |
| **Kiwify** | its 10 real triggers: `compra_aprovada`, `pix_gerado`, `boleto_gerado`, `compra_recusada`, `compra_reembolsada`, `chargeback`, `carrinho_abandonado`, `subscription_renewed`, `subscription_late`, `subscription_canceled` |
| **Nuvemshop** | the order's `payment_status` values: `paid`, `authorized`, `pending`, `refunded`, `partially_refunded`, `abandoned` — the Nuvemshop webhook carries only the ID, so the stage comes from the order's payment status |
| **Generic sources** | the documented event names from your system. You explicitly set the event field, ID, buyer/product/item paths and the canonical stage for each event; nothing is inferred from a platform name |

Managed sources with no verified sale-lifecycle contract, such as **Mercado Livre and OLX**, do not show
an event selector. Sources powered by the generic connector — including a custom Shopify/API setup —
show the signed generic webhook configuration and only receive the events you explicitly map.

The defaults are sensible: you only change the mapping if you want a different stage, or if you want to
ignore an event.

### Who appears as the recovery card's author

When an **active AI assistant or bot** sends the recovery card, the message is recorded with that bot
as its author. It must be active in the **conversation's inbox**, in the **same account**, and the
event used for recovery must belong to the **same contact as the conversation**.

When a **human agent** sends the card, the message is recorded with that agent as its author.

## Use cases

- **Abandoned cart**: triggers a Follow-up sequence reminding the customer to finish.
- **Pending PIX/boleto**: resends the payment code and follows up until confirmed.
- **Approved purchase**: confirms with the customer and unlocks the next support step.
- **Refund/decline**: alerts the team to handle the case right in the conversation.

## Tips, limits & best practices

- **What each platform exposes varies**: some send the **PIX code and the boleto line** in the event
  (full recovery inside the conversation); others only provide the **checkout link** — in those cases,
  the card shows the link for the customer to complete.
- **Amounts and formats differ per platform**: ConversaLabs normalizes each event; you don't need to
  worry about conversion — the card already displays the correct amount.
- **Verification secret**: keep it configured so only legitimate events from the platform are accepted.
  Hotmart, Kiwify, Nuvemshop and generic webhooks are rejected when no secret is configured. A generic sender must
  also provide the documented timestamped signature and one stable delivery ID per event.
- Combine with Follow-ups to automate recovery instead of relying on manual action.

A recorded message or a card visible in the conversation does not confirm delivery through the
customer's channel. Before saying the customer received it, check the **message's delivery status**
and the **channel connection**.

## Troubleshooting

- **A resend received no confirmed response**: the server may already have accepted the card. The
  panel blocks another attempt and offers **Check recorded outcome**, which only reads records.
  If no outcome can be verified yet, review the conversation; this check does not resend the card.
  The protection remains on closing and reopening confirmation. With browser session storage
  available, it also survives reloading in the same tab; if storage is denied, it lasts while the
  panel is mounted. This is not delivery proof or protection across browser tabs.
- **The charge status changed**: an old confirmation event is not resent when the current native
  charge is refunded, canceled or in another incompatible state. Review **Payments**.
- **PIX/boleto disappeared after payment**: old instruments remain in history, but are no longer
  offered for settled, refunded, canceled or archived charges. A partial refund does not create a
  new debt. Genuinely open installments of a plan retain their payment actions.
- **A confirmation cannot be sent outside the WhatsApp window**: use an approved confirmation
  template without a configured payment button. A collection template is not reused for a settled
  charge. Check that its approved content and static buttons also match the confirmation's purpose.

- **The event doesn't appear**: check that the complete webhook URL was pasted correctly into the
  platform and that the verification secret is configured and matches.
- **I don't see PIX/boleto on the card**: not every platform exposes that data; when it doesn't, the
  card carries the checkout link.
- **Duplicate events**: generic deliveries with the same delivery ID are acknowledged only once. If
  something looks off, confirm that the sender reuses that ID on retries and that only one webhook is
  configured for the same source.
- **The bot doesn't send the recovery card**: check that it is active in the conversation's inbox,
  in the same account, and that the event belongs to the same contact as the conversation.
- **The card appears, but the customer didn't receive it**: check the message's delivery status and
  the channel connection before confirming receipt to the customer.

## See also

- [Catalog & Commerce overview](/hc/ajuda/articles/catalog-commerce-overview-en)
- [Send a product and receive orders in the conversation](/hc/ajuda/articles/catalog-commerce-enviar-produto-pedido-na-conversa-en)
- [Native catalog: products, categories, images and prices](/hc/ajuda/articles/catalog-commerce-catalogo-nativo-en)