---
title: "Execute a GraphQL query"
method: POST
path: "/graphql"
tags: ["GraphQL"]
---

# Execute a GraphQL query

`POST /graphql`

Send a read-only GraphQL query to retrieve your payins, payouts, claims, movement balances, report balances, or aggregations. Provide a JSON body with a `query` string and optional `variables` and `operationName`. Results are automatically scoped to the merchant resolved from your credentials.

## Request body

- GraphQLRequest — A GraphQL request body. Send your query as a string, with optional variables and an optional operation name.
  - `query` string, required — The GraphQL query document. This API supports queries only.
  - `variables` object, nullable — A map of variable names to values referenced by the query.
  - `operationName` string, nullable — The name of the operation to execute when the document defines more than one.

## Response `200`

The GraphQL response envelope. A successful query returns a `data` object. Field-level or governance failures are returned in the `errors` array; GraphQL transport errors are also delivered here with HTTP 200.

- GraphQLResponse — The GraphQL response envelope. Contains `data` on success and/or an `errors` array when one or more errors occur.
  - `data` object, nullable — The query result. Its shape mirrors the fields you requested (for example `payins`, `reportBalances`, or `aggregations`).
  - `errors` GraphQLError[], nullable — One or more errors raised while processing the query.
    - `message` string, required — A human-readable description of what went wrong.
    - `path` string[], nullable — The response path to the field that raised the error.
    - `locations` object[], nullable — The locations in the query document related to the error.
      - `line` integer
      - `column` integer
    - `extensions` ErrorExtensions — Structured error metadata. `code` is a deterministic, stable error code and `retryable` indicates whether the request may be safely retried.
      - `code` 'PAGE_SIZE_EXCEEDED' | 'DATE_WINDOW_EXCEEDED' | 'INVALID_DATE_RANGE' | 'QUERY_DEPTH_EXCEEDED' | 'CURSOR_EXPIRED' | 'INVALID_CURSOR' | 'UNAUTHORIZED' | 'MERCHANT_ID_MISSING' | 'FORBIDDEN' | 'MERCHANT_CONCURRENCY_LIMIT_EXCEEDED' | 'GLOBAL_CONCURRENCY_LIMIT_EXCEEDED' | 'QUERY_TIMEOUT' | 'DATABRICKS_ERROR' | 'INTERNAL_ERROR' | 'SERVICE_UNAVAILABLE' | 'INVALID_FILTER' | 'VALIDATION_ERROR' | 'NOT_FOUND' | 'CONFLICT' | 'TOO_MANY_REQUESTS' — Deterministic error code returned in `errors[].extensions.code`.
      - `retryable` boolean — True when the error is transient and the request may be safely retried (timeouts, concurrency limits, service-unavailable, and data-platform errors).
      - `detail` string, nullable — Optional additional context, such as which filter was invalid.
      - `traceId` string, nullable — A trace identifier you can quote when contacting support.

## Other responses

- `400` — The request body could not be parsed as a valid GraphQL request (for example, malformed JSON or a missing `query` field).
- `401` — Authentication failed because credentials were missing or invalid. Provide a valid Shop ID and API token using HTTP Basic authentication.

---

[API](https://skmtc.net/payretailers/apis/transaction.md) · [All operations](https://skmtc.net/payretailers/apis/transaction/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/payretailers/transaction/revisions/b022ee3a593d/schema)