---
title: "List merchants"
method: GET
path: "/v1/merchants"
tags: ["Merchant"]
---

# List merchants

`GET /v1/merchants`

Returns a paginated list of merchants (normalized payees) linked to the
company's transactions. Access requires an admin or one of the
`transactions_rules_view` / `transactions_rules_manage` permissions. The result
is scoped to the merchants referenced by the company's ledger transactions.

Merchants are used to group and label card spend (e.g. resolving "AMZN MKTP US"
to "Amazon") and to power transaction rules. All operators in
[Filters](https://docs.cardda.com/docs/filters) are supported on the columns
below.

## Query parameters

- `company_id` string, uuid
- `_start` integer
- `_end` integer
- `_order` 'asc' | 'desc'
- `_field` string
- `id` string
- `name` string

## Headers

- `company-id` string, uuid, required

## Response `200`

Paginated list of merchants. Headers include `X-Total-Count` and
`Content-Range` for offset pagination — see [Pagination](https://docs.cardda.com/docs/pagination).

- Merchant[]
  - `id` string, uuid
  - `name` string — Normalized merchant name.
  - `image_url` string, nullable — Logo / image URL for the merchant.
  - `created_at` string, date-time
  - `updated_at` string, date-time

## Other responses

- `401` — Unauthorized — missing or invalid bearer token, or the caller lacks the `transactions_rules_view` / `transactions_rules_manage` permission and is not an admin (Pundit authorization failure). A non-admin caller must supply company context via the `company-id` header (or a `company_id` query param): `index?` is permission-based (`permission?` needs a company membership) and the non-admin scope is company-scoped, so without it the request lands here. Returned with an empty body.

---

[API](https://skmtc.dev/cardda/apis/banking-api.md) · [All operations](https://skmtc.dev/cardda/apis/banking-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/cardda/banking-api/revisions/ff1aeb3fda8b/schema)