Skip to content

Merchant Management

This endpoint group is for partners managing their merchants.

A partner manages two things across its merchants: the merchants themselves, and their API keys.

Every endpoint in this group requires a partner API token. A merchant API token is rejected with a 403 response, even one belonging to a merchant the partner account manages. This holds even for the API key endpoints below, which act on a merchant's behalf.

API keys are specific to a single merchant. They are not interchangeable between merchants, even merchants managed by the same partner. A partner API key can be created only in the partner dashboard. Standalone merchants, those not managed by any partner, manage their own API keys through the merchant Flute dashboard instead of this group.

To generate an API token from an API key, see GET /oauth-token. For more information about API keys, see Creating an API Key.

This Partner group consists of the following endpoints:

Operations

Lists the partner's merchants

Request

GET {{baseURL}}/v2/partner/merchants

This endpoint lists the merchants managed by the partner account.

Each entry reports the merchant's status, MCC (merchant category code), main contact, API key count, and last-30-days transaction figures.

This endpoint supports free-text search across company name, contact first and last name, contact email, and merchant id with search, and filtering by merchantStatus, mccCode, and date ranges. Date bounds are ISO 8601 date-times, both inclusive. A value without an offset is read as UTC. A …To date alone covers that whole day (createdTo=2026-03-10 includes all of March 10).

This endpoint requires a partner API token. A merchant API token, even one belonging to a merchant managed by the partner account, is rejected with a 403 response. A token that resolves to neither a merchant nor a partner also returns a 403 response. The partner account must also have the GeneralConfigurations permission. Otherwise, the request returns a 403 response.

See Also:
To create an API key for one of these merchants, see POST /v2/partner/api-keys.
To list API keys across these merchants, see GET /v2/partner/api-keys.
To revoke an API key, see DELETE /v2/partner/api-keys/{{clientId}}.

[ Request body ] [ Response body ]

Security
Bearer
Query
pageIndexinteger, (int32), >= 0

Specifies the page number of the returned search results.

A page is considered each set of the pageSize values.

The page count is zero-based. The maximum for pageIndex, or the page number, is the pageSize divided by the total count rounded down. For example, the pageSize is 50 and the total is 130. That means there are three pages, but the pageIndex value is in the inclusive range from zero to two.

Value restrictions include:

  • A value less than zero is not permitted.
  • Values equal to or greater than totalPages end successfully but will not return any items.

For page size information, see pageSize.

Example: 0

Default:0
pageSizeinteger, (int32), [ 1 .. 100 ]

Specifies the number of items for each page of the returned search results.

A page is considered each set of the pageSize values.

The page count is zero-based. The maximum for pageIndex, or the page number, is the pageSize divided by the total count rounded down. For example, the pageSize is 50 and the total is 130. That means there are three pages, but the pageIndex value is in the inclusive range from zero to two.

For page numbering information, see pageIndex.

Example: 50

Default:20
sortBystring

Specifies the field to sort by.

Valid values are:

ValueDescription
contactFirstNameSorts by the main contact's first name.
contactLastNameSorts by the main contact's last name.
createdOnSorts by when the merchant was created.
lastTransactionOnSorts by the merchant's latest transaction. Merchants that never transacted sort as the oldest.
merchantCompanyNameSorts by the merchant's company name. This is the default.
merchantStatusSorts by the status name.
transactionCount30DaysSorts by the last-30-days transaction count.
transactionVolume30DaysSorts by the last-30-days transaction volume.

Example: merchantCompanyName

Default:"merchantCompanyName"
Example:sortBy=merchantCompanyName
sortOrderstring, <= 4 characters

Specifies the sort order.

The sort order is specified by the sortOrder value.
The field that gets sorted by is specified by the sortBy value.

Valid values are:

ValueDescription
ascSorts results in ascending order, from the lowest value to the highest, or from the oldest timestamp to the most recent.
descSorts results in descending order, from the highest value to the lowest, or from the most recent timestamp to the oldest.
Default:"desc"
Example:sortOrder=desc
searchstring

Specifies a free-text, case-insensitive filter.

This value matches the company name, the main contact's first and last name (also "first last"), the main contact's email, and the merchant id.

Example: Peppared Street Cafe

Example:search=Peppared Street Cafe
merchantStatusstring

Filters to merchants in this status.

Example: Active

Enum:"Active""Closed""Suspended"
Example:merchantStatus=Active
mccCodestring

Filters to merchants with this MCC (merchant category code).

Example: 5411

Example:mccCode=5411
createdFromstring, (ISO 8601 date-time)

Filters by the earliest inclusive created date (in an ISO 8601 date-time UTC format).

If only createdFrom is specified, the search returns all available items from the createdFrom value to the present. The fields createdFrom and createdTo may be used together to create an inclusive range. We recommend creating an inclusive range to avoid a potentially excessive number of returns.

Example: 2026-02-19T20:24:52.934Z

Example:createdFrom=2026-02-19T20:24:52.934Z
createdTostring, (ISO 8601 date-time)

Filters by the latest inclusive created date (in an ISO 8601 date-time UTC format).

If only createdFrom is specified, the search returns all available items from the createdFrom value to the present. The fields createdFrom and createdTo may be used together to create an inclusive range. We recommend creating an inclusive range to avoid a potentially excessive number of returns.

Example: 2026-03-06T14:24:52.934Z

Example:createdTo=2026-03-06T14:24:52.934Z
lastTransactionFromstring, (ISO 8601 date-time)

Filters by the merchant's last transaction at or from this date (in an ISO 8601 date-time UTC format).

If only lastTransactionFrom is specified, the search returns all available items from the lastTransactionFrom value to the present. The fields lastTransactionFrom and lastTransactionTo may be used together to create an inclusive range. We recommend creating an inclusive range to avoid a potentially excessive number of returns.

Example: 2026-02-19T20:24:52.934Z

Example:lastTransactionFrom=2026-02-19T20:24:52.934Z
lastTransactionTostring, (ISO 8601 date-time)

Filters by the merchant's last transaction at or before this date (in an ISO 8601 date-time UTC format).

If only lastTransactionTo is specified, the search returns all available items from the lastTransactionTo value to the present. The fields lastTransactionFrom and lastTransactionTo may be used together to create an inclusive range. We recommend creating an inclusive range to avoid a potentially excessive number of returns.

Example: 2026-02-19T20:24:52.934Z

Example:lastTransactionTo=2026-02-19T20:24:52.934Z
// Language is not supported.

Responses

OK

Bodyapplication/json
itemsArray of objects

Indicates the merchants on the current page.

It is empty when the requested page is beyond the data, or no merchant matches the filters.

pageInfoobject

Indicates an object describing the pagination status.

If additional pages to review are needed, repeat the exact same search but include a new pageIndex value. Typically, this will increment the current pageIndex by one. However, any valid value may be used. Value restrictions include:

  • A value less than zero is not permitted.
  • Values equal to or greater than totalPages end successfully but will not return any items.
Response

The first page of merchants, sorted by company name, with no filters applied.

{
  "items": [
    {
      "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "merchantCompanyName": "Peppared Street Cafe",
      "merchantStatus": "Active",
      "mccCode": "5411",
      "mccDescription": "Grocery Stores and Supermarkets",
      "contactFirstName": "Alexandro",
      "contactLastName": "Peppared",
      "transactionCount30Days": 142,
      "transactionVolume30Days": 18500,
      "apiKeyCount": 1,
      "createdOn": "2026-01-15T10:00:00.821Z",
      "lastTransactionOn": "2026-06-24T19:27:05.021Z"
    }
  ],
  "pageInfo": {
    "pageIndex": 0,
    "pageSize": 20,
    "totalItems": 150,
    "totalPages": 8,
    "hasMore": true
  }
}