Overview
History import brings gateway charges, customer mappings, and subscriptions into Conversa Labs. Charges create financial events, Orders, and reports; subscriptions appear in Payments > Subscriptions; and an imported customer only creates a technical mapping to a contact that already exists in the account.
The process is governed: a preview does not write charges, mappings, or subscriptions; it persists only the audited run and the snapshot used to review the selection. A real import includes only records you select. The platform never creates contacts or organizations silently: a charge without an exact match remains blocked until you choose an existing contact or propose a new one, which is created only after final confirmation. When a charge and subscription carry the same gateway subscription identifier, they are linked to each other even if you import them in either order. Historical charges do not send customer messages, advertising conversions, commissions, or outbound webhooks.
Prerequisites
- You must be an account administrator.
- The Asaas or Mercado Pago connection must be active and its credentials verified.
- For Mercado Pago charges, choose a start date within the previous 12 months. The complete search for that resource follows this rolling window.
- For Mercado Pago customers, enter the customer email. Its documented API does not provide an account-wide customer sweep.
- Review the import watermark before allowing automatic adoption of unknown charges from webhooks.
Step by step
- Go to Settings > Payments > Connections and choose Import history on the required connection. You can also open the action from the empty state in Charges.
- Under Resource to import, choose Charges, Customer mappings, or Subscriptions. Ingestion safeguards and automatic adoption apply only to charges.
- For charges, set the watermark and keep automatic adoption disabled unless your operation has a clear rule for it. “Only from the watermark” requires a valid watermark.
- Enter the period and record limit. For a Mercado Pago customer, also enter the email. Choose Generate preview.
- Review the detailed list. Each charge shows the customer data supplied by the gateway, the contact found, and the exact signal used for the association. Search by identifier, reference, or customer; combine filters; change sorting; and move through pages without losing selections made on other pages.
- For a charge marked Customer pending, choose an existing contact or propose a new one with a name and at least one identifier (email, phone, or document). The proposal creates nothing during preview. Automatic matches use only exact gateway customer, email, normalized phone, or document signals; similar names are never enough.
- Use Select importable records on this page, Select every importable record in these filters (when the preview spans more than one page), or select each row. Global selection spans every page in the current slice but reaches only importable records with a resolved customer: skipped, already-synced, or pending rows are never selected. Changing a filter intentionally clears selection; changing pages preserves it. The connection, run, filters, and sorting are stored in the URL, so back, forward, and a reopened link restore the same view only when the connection belongs to the current account.
- Choose Import selected, review the exact count and customer resolutions in the confirmation, and confirm. An empty selection never means “import everything”. Proposed contacts are created inside the confirmed import; if validation fails, the corresponding charge does not enter without a contact.
- Follow the result and connection history. Failed records show their identifier and reason; success never includes a row that failed.
Settings & options
Watermark and automatic adoption
The watermark limits historical ingestion. Automatic adoption of charges arriving through webhooks is disabled by default. If you enable adoption from the watermark, the platform fails safely when the watermark is missing or invalid.
Preview list
The preview is a safe snapshot of the same execution that would import the data, without writing charges, mappings, or subscriptions. The list uses server pagination and totals; its counter is not derived only from the visible page. On small screens, filters and sorting open in their own panel and every row becomes a readable card.
Chips show active filters. Clear filters is available when a combination returns no results. If the requested limit is reached, the preview reports that it was truncated: generate another window instead of assuming all history was read.
Ignored records
In a preview, use the block icon next to a record to ignore it permanently and provide a reason. The decision is separated by charge, customer, or subscription even if the gateway reuses an identifier. Under Permanently ignored records, choose Allow again to undo the decision.
Contact and organization links
The platform first looks for exact matches by gateway customer, email, normalized phone, document, and CNPJ. For a charge without a contact, you must choose an account contact or propose a new contact before selecting it. Creation is delayed until confirmation, and a manual link is never silently replaced. An unmatched subscription stays visible for later reconciliation; an unmatched directory customer is skipped because there is no safe local owner for a mapping. Charges and subscriptions are connected only by the exact identifier supplied by the gateway, never by amount, date, or name.
Use cases
- Recover charges, Orders, and subscriptions after connecting a gateway that already had sales.
- Import Asaas customer mappings before subscriptions to increase exact association by gateway identifier.
- Rebuild internal reports without notifying customers about old transactions.
- Permanently exclude a charge belonging to another operation or one that is not a sale.
- Import a small period first, validate the preview, then continue in smaller windows.
Tips, limits & best practices
- Start with a short window and small record limit; expand only after reviewing the preview.
- Each preview/import and each explicit selection accepts at most 5,000 records.
- A confirmed import must use exactly the same resource type, window, limit, and email as its completed preview. Generate a new preview after changing any parameter; this applies to charges, customers, and subscriptions.
- Selection is required. The platform never treats an empty selection as “import everything”.
- Selection survives pagination and Select all spans every page in the current filters, but it is cleared when search or filters change so an invisible row is never imported by mistake.
- Charges without a resolved contact cannot be selected. Resolve each one manually; the API also blocks attempts to bypass the preview.
- The durable ignore list is loaded completely through internal pages; more than 100 exclusions never disappear silently.
- Customers do not use date filters and can only map an existing contact. Mercado Pago customer search is always email-targeted.
- Totals are shown per currency; do not add different currencies as one amount.
- Reversal removes only local records created by that execution. It never changes the gateway.
- To reverse, open an eligible execution in history, type
undo, and confirm. If a later charge, customer mapping, subscription, Order, or event movement changed the data, the full reversal is refused to preserve the audit trail. Reversal removes only records and links created by the run; contacts and organizations are preserved, including a manually proposed and confirmed contact. - Older runs made before the reversal ledger may not be eligible. Keep their history and use the normal financial operation for corrections.
Troubleshooting
Mercado Pago requires a start date
Enter a date within Mercado Pago's supported history window. An older date could create an incomplete view and is refused by the platform.
I cannot import without selecting records
This is expected. Generate a preview, select the intended records, and run the selected import.
A charge cannot be selected because its customer is pending
Open customer resolution on that row. Choose an existing contact or propose a new one with a name and an email, phone, or document. Save the decision, select the charge, and confirm the import. A proposed contact does not exist until that confirmation.
Mercado Pago requires the customer email
This is expected. Mercado Pago's documented customer search requires email and does not allow a general address-book import. Enter the email for the existing customer you want to map, or import subscriptions, which try to associate the payer data supplied by the gateway.
A charge is shown as ignored
Open Permanently ignored charges on the same screen, review the reason, and choose Allow again if it may be considered again.
Reversal was refused
A later movement occurred, or the record was not created by the chosen execution. No data was removed. Review the history row and charge events, then use the appropriate normal financial operation.