## Tool: `query_merchant_performance`

Retrieves high-level aggregated performance data and post-integration metrics for a specific merchant business profile.

The following code sample shows how to use `curl` to call the `query_merchant_performance` MCP tool.

| Curl Request |
|---|
| ```bash curl --location 'https://paydeveloper.googleapis.com/mcp' \ --header 'content-type: application/json' \ --header 'accept: application/json, text/event-stream' \ --data '{ "method": "tools/call", "params": { "name": "query_merchant_performance", "arguments": { // Provide these details according to the MCP tool specification. } }, "jsonrpc": "2.0", "id": 1 }' ``` |

## Input Schema

Request message for querying merchant performance data.

### QueryMerchantPerformanceRequest

| JSON representation |
|---|
| ``` { "merchantId": string, "timeRange": enum (`https://developers.google.com/pay/api/android/reference/mcp/tools_list/query_merchant_performance#Input.Schema.TimeRange`) } ``` |

| Fields ||
|---|---|
| `merchantId` | `string` Required. The unique identifier of the merchant for which performance data is being requested. |
| `timeRange` | ``enum (`https://developers.google.com/pay/api/android/reference/mcp/tools_list/query_merchant_performance#Input.Schema.TimeRange`)`` Optional. The time range of the performance data. |

### TimeRange

The time range of the data. Next ID: 4

| Enums ||
|---|---|
| `TIME_RANGE_UNSPECIFIED` | Unspecified time range. |
| `TIME_RANGE_PAST_DAY` | The past day, yesterday. |
| `TIME_RANGE_PAST_THREE_DAYS` | The past three days, excluding the current day. |
| `TIME_RANGE_PAST_WEEK` | The past week, excluding the current day. |

## Output Schema

Response message for querying merchant performance.

### QueryMerchantPerformanceResponse

| JSON representation |
|---|
| ``` { "merchantPerformanceMetrics": [ { object (`https://developers.google.com/pay/api/android/reference/mcp/tools_list/query_merchant_performance#Output.Schema.MerchantPerformanceMetric`) } ] } ``` |

| Fields ||
|---|---|
| `merchantPerformanceMetrics[]` | ``object (`https://developers.google.com/pay/api/android/reference/mcp/tools_list/query_merchant_performance#Output.Schema.MerchantPerformanceMetric`)`` The performance data of the merchant. |

### MerchantPerformanceMetric

| JSON representation |
|---|
| ``` { "metricDetail": { object (`https://developers.google.com/pay/api/android/reference/mcp/tools_list/query_merchant_performance#Output.Schema.MetricDetail`) }, "hourlyMetricValues": [ { object (`https://developers.google.com/pay/api/android/reference/mcp/tools_list/query_merchant_performance#Output.Schema.HourlyMetricValue`) } ] } ``` |

| Fields ||
|---|---|
| `metricDetail` | ``object (`https://developers.google.com/pay/api/android/reference/mcp/tools_list/query_merchant_performance#Output.Schema.MetricDetail`)`` Output only. Details of the metric. |
| `hourlyMetricValues[]` | ``object (`https://developers.google.com/pay/api/android/reference/mcp/tools_list/query_merchant_performance#Output.Schema.HourlyMetricValue`)`` Output only. A list of metric value and its timestamp, rounded to the nearest top of hour. |

### MetricDetail

| JSON representation |
|---|
| ``` { "metricType": enum (`https://developers.google.com/pay/api/android/reference/mcp/tools_list/query_merchant_performance#Output.Schema.MetricType`), "additionalDetails": { string: string, ... } } ``` |

| Fields ||
|---|---|
| `metricType` | ``enum (`https://developers.google.com/pay/api/android/reference/mcp/tools_list/query_merchant_performance#Output.Schema.MetricType`)`` Type of the metric. |
| `additionalDetails` | `map (key: string, value: string)` Key-value pairs for any additional details about the metric, e.g., "gateway": "stripe". For details see An object containing a list of `"key": value` pairs. Example: `{ "name": "wrench", "mass": "1.3kg", "count": "3" }`. |

### AdditionalDetailsEntry

| JSON representation |
|---|
| ``` { "key": string, "value": string } ``` |

| Fields ||
|---|---|
| `key` | `string` |
| `value` | `string` |

### HourlyMetricValue

| JSON representation |
|---|
| ``` { "hourlyTimestamp": string, "value": number } ``` |

| Fields ||
|---|---|
| `hourlyTimestamp` | ``string (`https://protobuf.dev/reference/protobuf/google.protobuf#timestamp` format)`` The timestamp of the metric value rounded to the nearest top of hour. Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: `"2014-10-02T15:01:23Z"`, `"2014-10-02T15:01:23.045123456Z"` or `"2014-10-02T15:01:23+05:30"`. |
| `value` | `number` The actual metric value. For conversion rate, the value is in the range of \[0, 1\]. For other metrics, the value is non-negative integer. |

### Timestamp

| JSON representation |
|---|
| ``` { "seconds": string, "nanos": integer } ``` |

| Fields ||
|---|---|
| `seconds` | `string (https://developers.google.com/discovery/v1/type-format format)` Represents seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z. Must be between -62135596800 and 253402300799 inclusive (which corresponds to 0001-01-01T00:00:00Z to 9999-12-31T23:59:59Z). |
| `nanos` | `integer` Non-negative fractions of a second at nanosecond resolution. This field is the nanosecond portion of the duration, not an alternative to seconds. Negative second values with fractions must still have non-negative nanos values that count forward in time. Must be between 0 and 999,999,999 inclusive. |

### MetricType

The type of metric being measured.

| Enums ||
|---|---|
| `METRIC_TYPE_UNSPECIFIED` | Unspecified metric type. |
| `FACILITATION_COUNT` | The number of successful GPay API facilitation. |
| `VISIT_COUNT` | The number of clicks on the GPay API button. |
| `CONVERSION_RATE` | The conversion rate of the checkout button, defined as the ratio of the number of successful GPay API facilitation to the number of clicks on the GPay API button. |

### Tool Annotations


[Tool annotations](https://modelcontextprotocol.io/specification/latest/schema#toolannotations) are sent to MCP clients to describe the basic risk of a given tool. Most clients treat these hints as untrusted, but they can be used to decide when a confirmation prompt might be sent to a user.


Along with the title string, the following boolean hints are defined as follows:

- `readOnlyHint`: If true, the tool doesn't modify its environment. Default: false.
- `destructiveHint`: If true, then the tool can perform destructive actions. If false, then the tool can only perform additive actions. Default: true.
- `idempotentHint`: If true, then calling the tool repeatedly with the same arguments will have no additional effect on its environment. Default: false.
- `openWorldHint`: If true, then the tool can interact with an 'open world' of external entities. If false, then the tool can only interact with internal entities. For example, a web search tool would be open world, while a memory tool would not be open world.

Destructive Hint: ❌ \| Idempotent Hint: ✅ \| Read Only Hint: ✅ \| Open World Hint: ❌