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

# Deals

> A Kanban sales pipeline that tracks opportunities from first WhatsApp contact through to closed-won.

**Deals** turns Soneka into a lightweight CRM. Each opportunity is a card on a Kanban board that moves through your sales stages, carries a value and an owner, and stays wired to the WhatsApp conversation it came from.

<Info>
  Deals is plan-gated by the **`access_sales_pipeline`** feature switch. If you don't see **Deals** in the sidebar, ask the platform admin to enable it on your plan.
</Info>

## The pipeline board

**Sidebar → Deals** opens the Kanban board. Columns are your **stages** — out of the box you get:

1. **New** — fresh opportunity, not yet qualified.
2. **Qualified** — fits the buyer profile.
3. **Proposal** — quote or offer sent.
4. **Negotiation** — working out terms.
5. **Won** — closed successfully.
6. **Lost** — closed unsuccessfully (with a required reason).

Rename, reorder, add, or archive stages under **Deals → Settings → Stages**. Cards drag freely between columns; every move is logged on the deal's timeline.

### What a deal card holds

| Field                   | Notes                                                                                 |
| ----------------------- | ------------------------------------------------------------------------------------- |
| **Title**               | Free-text name.                                                                       |
| **Contact**             | Linked WhatsApp contact. One click opens the chat.                                    |
| **Value**               | Amount and currency. Rolled up into stage totals.                                     |
| **Owner**               | The agent responsible. Auto-set from assignment when the deal is created from a chat. |
| **Expected close date** | Drives the forecast view.                                                             |
| **Tags**                | For filtering the board.                                                              |
| **Custom fields**       | Anything you add under **Settings → Custom fields**.                                  |
| **Notes & activity**    | Free-text notes plus an automatic timeline (stage changes, messages, tasks).          |

## Creating deals

Deals can be created five ways:

<Steps>
  <Step title="From a conversation">
    In the Team Inbox, open the contact panel and click **+ New deal**. The contact, owner, and channel are pre-filled.
  </Step>

  <Step title="From the Deals board">
    Click **+ New deal** in any column. Pick a contact or create one on the fly.
  </Step>

  <Step title="From a flow">
    Drop a **Create Deal** node into the Flow Builder. Map value, stage, tags, and custom fields from previous steps (form answers, attributes, or catalog interactions).
  </Step>

  <Step title="From an import">
    **Deals → Import** takes a CSV with `title, contact_phone, value, currency, stage, owner_email`. Rows with unknown contacts create the contact automatically.
  </Step>

  <Step title="From the API">
    `POST /api/v1/deals` with an API token from **Settings → Developers**. See below.
  </Step>
</Steps>

## Automating with flows

Deals are first-class citizens in the Flow Builder, in both directions:

* **Create Deal** / **Update Deal** / **Move Deal Stage** nodes let a flow write to the pipeline.
* **When deal stage changes** triggers a flow when a human (or another flow) moves a card. Use this to fire follow-up messages when someone reaches **Proposal**, or to notify a manager on **Won**.

Example: kick off a nurture sequence the moment a deal moves to Qualified.

```text theme={null}
[Trigger: deal moved to "Qualified"] → [Wait 1 hour]
                                       → [Send template: case-study]
                                       → [Wait 2 days]
                                       → [Send template: pricing]
```

## Views

Switch between:

* **Board** — Kanban, drag-and-drop.
* **List** — sortable table, great for bulk edits.
* **Forecast** — groups by expected close month with a weighted total based on stage probability.

Each view respects the current filter set (owner, tag, value range, stage, custom fields).

## REST API

Available endpoints (token from **Settings → Developers**):

| Method   | Path                       | Purpose                                |
| -------- | -------------------------- | -------------------------------------- |
| `GET`    | `/api/v1/deals`            | List deals with filter and pagination. |
| `POST`   | `/api/v1/deals`            | Create a deal.                         |
| `GET`    | `/api/v1/deals/{id}`       | Fetch a single deal.                   |
| `PATCH`  | `/api/v1/deals/{id}`       | Update fields.                         |
| `POST`   | `/api/v1/deals/{id}/stage` | Move to a new stage.                   |
| `DELETE` | `/api/v1/deals/{id}`       | Archive.                               |

```bash theme={null}
curl -X POST https://your-soneka.example.com/api/v1/deals \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Acme — 30 seats",
    "contact_phone": "+254700000000",
    "value": 4500,
    "currency": "USD",
    "stage": "Proposal",
    "owner_email": "jane@example.com"
  }'
```

## Reporting

A dedicated **Sales** section in Analytics shows:

* Pipeline value by stage
* Conversion rates between stages
* Win rate by owner and by source
* Sales-cycle length (time from **New** to **Won**)

## Troubleshooting

<Warning>
  **Deals sidebar item is missing.** The plan on your workspace doesn't have `access_sales_pipeline` enabled. Ask the platform owner to update the plan.
</Warning>

<Warning>
  **Flow can't move a deal.** The Move Deal node needs the deal ID (from a previous Create Deal node or an attribute). If the deal was created outside the flow, look it up first with a Get Deal node.
</Warning>

## Related

* [Team Inbox](/features/team-inbox) — create deals from a live chat and jump back to the conversation from any card.
* [Flow Builder](/features/flow-builder) — automate pipeline movement and stage-based follow-up.
* [Analytics](/features/analytics) — pipeline value, conversion, and sales-cycle reports.