## Overview

The **Orders Registry** is a contact-centric **purchase history**. For each contact (and, optionally, for
each deal) you record orders with a **title, value, currency, status and date**, building a clear view of
everything that person has bought.

It's important to understand what it **is** and what it **is not**: the orders registry is a **log**, not a
payment gateway. It **does not charge, refund or reconcile money** — billing is handled by the **Payments**
module. Changing a manual order status does not call the gateway; however, a financial status feeds internal
commissions, stock, goals, and automations, so it requires authorization and an audit trail.

Orders can arrive from several origins: entered **manually**, received via **webhook**, created through the
**API**, originated from the **Payments** module, or from **commerce** integrations.

### How to edit and change status

- A non-financial **manual** order can have its title, amount, currency, date, and status corrected by a CRM
  manager.
- Entering **partially paid**, **paid**, or **refunded** requires sales-management authority and a reason.
  The before/after state, actor, and explanation are retained.
- Once financial effects exist, amount, currency, items, and deal cannot be rewritten in place. Use link
  repair or the governed void flow so commissions, stock, and goals remain consistent.
- An order from **Payments** or another integration is a synchronized projection. Open its details and use
  **Manage in Charges** to locate the source charge; `confirmed` and `paid` payments project as a paid order.
  Correct facts at the source and synchronize instead of editing the log.
- Before a financial or integration order is voided, the screen previews compensations and blockers. Closed
  commissions, confirmed bookings, granted rewards, or delivered distribution fail closed.

## Prerequisites

- The **Orders Registry** is optional and **off by default**. Ask an administrator to enable it for the
  account.
- **CRM management** permission to create and edit orders.
- Contacts in place — every order belongs to a contact.

## Step by step

1. Confirm with an administrator that the **Orders Registry** is enabled.
2. In the sidebar, open **Orders**. The page brings together the orders you are allowed to consult, including
   those linked to existing contacts and deals.
3. Use search, date range, source, gateway, status, **seller**, and sorting to find the required slice. Those
   filters stay in the page address, so they can be reloaded or shared. The seller filter is available to
   team managers and uses the canonical sale assignment.
4. Click any order title to open its details. The address identifies that order and can be reloaded or shared;
   linked contact, organization, deal, and charges appear as shortcuts according to your permission.
5. Create a manual order with an **existing contact**, **title**, **value**, **currency** and **status**.
6. When products are involved, inspect their name, quantity, unit price and discount; they preserve the
   financial snapshot of the sale.
7. Optionally, set the **order date** and link the order to a **deal**. Marking it paid records the paid date
   through the controlled flow.
8. Export the same slice as CSV or select manual orders for the available bulk action. Their checkbox is
   disabled and **Select every manual order in these filters** also reaches manual orders only. Integration orders are
   protected from editing and deletion in the screen.
9. If an integration order has the wrong customer or links, use **Fix the sale customer and links**. Choose
   the contact, review the related charge and recovery event, and apply the preview. This does not edit the
   order's financial snapshot and remains available when the integration record is immutable.

## Settings & options

- **Order status**: pending, paid, partially paid, partially refunded, overdue, refunded, canceled and failed. A partial refund keeps only the non-refunded balance as recognized revenue.
- **Source**: manual, webhook, API, Payments or commerce — identifies where the record came from.
- **Links**: every order belongs to a **contact** and can be linked to a CRM **deal**.
- **Currency and value**: each order has its own value and currency (default BRL).
- **External identifier**: orders from integrations carry an **external ID** that prevents duplicates.
- **Order items**: each item's name and amounts are a sale snapshot. Later Catalog changes do not rewrite what
  was sold; when available, the item also retains its link to the same account's product or variant.
- **Owner-based wallet**: when owner-based privacy is active, each rep sees only the orders of the
  contacts/deals they can access.
- **Global list and CSV**: the Orders page is server-paginated; export honors the current filters and selection
  without including data outside your scope.
- **Edit vs fix links**: only manual orders have normal edit and delete. The separate contact, organization,
  deal, and conversation correction preserves amount, status, items, dates, and external identity.
- **Integration vs manual order**: on orders created by Payments or an integration, amount and status follow
  the source and are not overwritten in the registry. Open the linked charge to cancel, refund, or reconcile.
  Manual orders remain editable from the details view.

## Use cases

- Keep each customer's **purchase history** right on the contact profile.
- Track, on the deal, the orders already placed for that opportunity.
- Consolidate orders from multiple origins (manual, Payments, commerce) into a single log.
- Feed automation and reports based on what each contact has bought.
- Compare a deal's quoted budget with the catalog items that were actually settled in the Catalog report.

## Tips, limits & best practices

- Use the orders registry for **history**; to actually **charge**, use the Payments module.
- Standardize **titles** and **statuses** to make reading and filtering easier.
- When integrating via webhook/API, send a stable **external ID** so orders aren't duplicated.
- When sending `partially_refunded`, also send `amount_refunded`, greater than zero and lower than the total.
- Send a stable item identifier for every integrated item too; a redelivery of the same order then does not
  duplicate its lines.
- Link the order to the matching **deal** when it makes sense, to connect sale and opportunity.
- Edit or delete **manual** records only. On an imported order, use **Fix customer and links** only for
  associations; correct amount, status, items, dates, or external ID at the source and synchronize again.

## Troubleshooting

- **I don't see the Orders section**: the module may be disabled for the account — talk to an administrator.
- **Duplicate order**: check that the integration is sending the same **external ID** instead of creating a
  new one.
- **The order didn't charge the customer**: that's expected — the registry is a log; charging is done in
  Payments.
- **The Catalog name or price changed**: the recorded item keeps the original sale snapshot; this is
  intentional to preserve financial history.
- **I can't create an order**: check your CRM management permission and that the contact exists.
- **I can't edit an imported order**: this is intentional. Records received from Payments, commerce, API or a
  webhook protect financial facts from redelivery. If only the customer or another association is wrong, use
  **Fix the sale customer and links** on the order row. To cancel, refund, or correct settlement, open the
  details and select **Manage in Charges**.
- **I can't change the status of a paid/integration order**: manage the operation on the linked charge or at
  its source gateway using the details shortcut. The webhook synchronizes the outcome without turning the
  registry into a second source of truth.

## See also

- [CRM: pipelines, kanban and deals](/hc/ajuda/articles/contacts-crm-crm-pipelines-kanban-negocios-en)
- [Deals: notes, attachments, checklists, line items and automatic value](/hc/ajuda/articles/contacts-crm-crm-notas-anexos-checklists-line-items-valor-en)
- [Contacts and CRM overview](/hc/ajuda/articles/contacts-crm-overview-en)

### Remove test or orphaned orders

In **Orders**, administrators can remove records created by charges or integrations. Select a correction type and enter a reason. The order immediately leaves the **Operational** view, while its source, actor, reason, and any compensations remain in the audit history.

A never-paid manual order without a linked charge can be deleted permanently. Paid or integration-backed orders are **voided**, not erased: open commissions, stock, and engagement score are compensated atomically. A closed commission blocks the operation to prevent financial divergence.

Use **Record state → Voided** to review removed records. Restore is available only when the void created no accounting, stock, or engagement compensation and the external identity is still available.

To purge the charge itself, archive it first. Only a non-settled charge can be deleted permanently; deletion requires a reason and voids/unlinks the related order before removing the local charge. These actions never cancel or refund money at the gateway.