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

# Merchants

> List, create, rename, and delete merchants (payees)

Merchants are the payees on your transactions. Kualia enriches many merchants automatically (logos, verified names); the API exposes the resolved display name.

## The merchant object

```json theme={null}
{
  "id": "k9921m...",
  "name": "Starbucks",
  "created_at": "2026-02-03T10:00:00.000Z",
  "updated_at": "2026-06-30T08:12:44.000Z"
}
```

## List merchants

```text theme={null}
GET /v1/workspaces/{workspace_id}/merchants
```

Returns all active merchants sorted by name.

## Get a merchant

```text theme={null}
GET /v1/workspaces/{workspace_id}/merchants/{merchant_id}
```

## Create a merchant

```text theme={null}
POST /v1/workspaces/{workspace_id}/merchants
```

```json theme={null}
{ "name": "Corner Bakery" }
```

Names are unique per workspace (case-insensitive); a duplicate returns `409 conflict`.

<Note>
  You usually don't need to create merchants explicitly — passing `merchant_name` when [creating a
  transaction](/api/transactions) finds or creates the merchant in one step.
</Note>

## Rename a merchant

```text theme={null}
PATCH /v1/workspaces/{workspace_id}/merchants/{merchant_id}
```

```json theme={null}
{ "name": "Corner Bakery Cafe" }
```

## Delete a merchant

```text theme={null}
DELETE /v1/workspaces/{workspace_id}/merchants/{merchant_id}
```

| Query parameter       | Type   | Description                                                                    |
| --------------------- | ------ | ------------------------------------------------------------------------------ |
| `move_to_merchant_id` | string | Reassign the merchant's transactions and planned transactions to this merchant |

Without `move_to_merchant_id`, the merchant's transactions keep their data but lose the payee. The response reports what moved:

```json theme={null}
{
  "data": {
    "deleted": true,
    "id": "k9921m...",
    "moved_transaction_count": 42,
    "updated_recurring_transaction_count": 1
  }
}
```