> For the complete documentation index, see [llms.txt](https://docs.gobtcpay.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.gobtcpay.com/api-reference/merchant-api/reports.md). # Reports Sales summaries, transaction and aggregated reports, and async exports. ## Sales summary > Returns headline sales \`totals\` (\`paymentsCount\`, \`grossAmount\`, \`grossSats\`, \`avgTicket\`, \`currency\`) plus a \`breakdown\` array for a \`dateRange\`, optionally narrowed by \`filters\` (\`storeIds\`, \`posIds\`, \`currency\`). ```json {"openapi":"3.1.0","info":{"title":"GoBTC Pay Merchant Account API","version":"1.45.2"},"tags":[{"name":"Reports","description":"Sales summaries, transaction and aggregated reports, and async exports."}],"servers":[{"url":"https://api.gobtcpay.com/public/api/v1.1"}],"security":[{"merchantAuth":[]}],"components":{"securitySchemes":{"merchantAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Merchant dashboard access token obtained from `/merchant/auth/login` (or the OAuth / passkey / 2FA login flows). Send it as `Authorization: Bearer `. Refresh it via `/merchant/auth/refresh` when it expires."}}},"paths":{"/merchant/reports/sales-summary":{"post":{"summary":"Sales summary","description":"Returns headline sales `totals` (`paymentsCount`, `grossAmount`, `grossSats`, `avgTicket`, `currency`) plus a `breakdown` array for a `dateRange`, optionally narrowed by `filters` (`storeIds`, `posIds`, `currency`).","tags":["Reports"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"dateRange":{"type":"object","properties":{"start":{"type":"integer","minimum":0,"description":"UnixTime (seconds since epoch)"},"end":{"type":"integer","minimum":0,"description":"UnixTime (seconds since epoch)"}},"required":["start","end"],"additionalProperties":false},"filters":{"type":"object","properties":{"storeIds":{"type":"array","items":{"type":"string"}},"posIds":{"type":"array","items":{"type":"string"}},"currency":{"type":"string","description":"Fiat currency code (ISO 4217), e.g. `USD`."}},"additionalProperties":false}},"required":["dateRange"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"result":{"type":"object","properties":{"$case":{"type":"string","const":"success"},"success":{"type":"object","properties":{"totals":{"type":"object","properties":{"paymentsCount":{"type":"number"},"grossAmount":{"type":"number"},"grossSats":{"type":"number"},"avgTicket":{"type":"number"},"currency":{"type":"string","description":"Fiat currency code (ISO 4217), e.g. `USD`."}},"required":["paymentsCount","grossAmount","grossSats","avgTicket","currency"],"additionalProperties":false},"breakdown":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string","description":"Human-readable label for the POS terminal (optional)."},"paymentsCount":{"type":"number"},"grossAmount":{"type":"number"},"grossSats":{"type":"number"}},"required":["key","label","paymentsCount","grossAmount","grossSats"],"additionalProperties":false}}},"required":["totals","breakdown"],"additionalProperties":false}},"required":["$case","success"],"additionalProperties":false}},"required":["id","result"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"500":{"description":"Error response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"statusCode":{"type":"number","description":"Numeric error status code."},"description":{"type":"string","description":"Human-readable description."},"statusMessage":{"type":"string","description":"Short machine-readable error message."}},"required":["statusCode","description","statusMessage"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}}}}}}} ``` ## Transactions report > Lists detailed report transactions for a \`dateRange\` with \`pagination\` (\`limit\`, \`skip\`) and optional \`filters\` (\`storeIds\`, \`posIds\`, \`status\`, \`currency\`); responds with \`items\`, \`totalCount\`, and aggregate \`totals\`. ```json {"openapi":"3.1.0","info":{"title":"GoBTC Pay Merchant Account API","version":"1.45.2"},"tags":[{"name":"Reports","description":"Sales summaries, transaction and aggregated reports, and async exports."}],"servers":[{"url":"https://api.gobtcpay.com/public/api/v1.1"}],"security":[{"merchantAuth":[]}],"components":{"securitySchemes":{"merchantAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Merchant dashboard access token obtained from `/merchant/auth/login` (or the OAuth / passkey / 2FA login flows). Send it as `Authorization: Bearer `. Refresh it via `/merchant/auth/refresh` when it expires."}}},"paths":{"/merchant/reports/transactions":{"post":{"summary":"Transactions report","description":"Lists detailed report transactions for a `dateRange` with `pagination` (`limit`, `skip`) and optional `filters` (`storeIds`, `posIds`, `status`, `currency`); responds with `items`, `totalCount`, and aggregate `totals`.","tags":["Reports"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"pagination":{"type":"object","properties":{"limit":{"type":"number","minimum":1,"maximum":100,"default":20},"skip":{"type":"number","minimum":0,"default":0}},"additionalProperties":false},"dateRange":{"type":"object","properties":{"start":{"type":"integer","minimum":0,"description":"UnixTime (seconds since epoch)"},"end":{"type":"integer","minimum":0,"description":"UnixTime (seconds since epoch)"}},"required":["start","end"],"additionalProperties":false},"filters":{"type":"object","properties":{"storeIds":{"type":"array","items":{"type":"string"}},"posIds":{"type":"array","items":{"type":"string"}},"status":{"type":"array","items":{"type":"string","enum":["success","failed","pending","cleared"]},"description":"Current status. Payments: `initiated` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`."},"currency":{"type":"string","description":"Fiat currency code (ISO 4217), e.g. `USD`."}},"additionalProperties":false}},"required":["dateRange"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"result":{"type":"object","properties":{"$case":{"type":"string","const":"success"},"success":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"paymentId":{"type":"string","description":"Identifier of the payment (UUID)."},"paymentTxId":{"type":"string","description":"Identifier of the payment transaction (UUID)."},"status":{"type":"string","enum":["success","failed","pending","cleared"],"description":"Current status. Payments: `initiated` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`."},"storeId":{"type":"string"},"storeName":{"type":"string"},"posTerminalId":{"type":"string","description":"Identifier of the POS terminal (UUID)."},"posTerminalLabel":{"type":["string","null"],"description":"Label of the POS terminal (may be null)."},"posTerminalLocation":{"type":["string","null"],"description":"Location of the POS terminal (may be null)."},"amountSats":{"type":"number","description":"Amount in satoshis."},"description":{"type":["string","null"],"description":"Human-readable description."},"createdAt":{"type":"integer","minimum":0,"description":"Creation time as a Unix timestamp (seconds)."},"btcPriceInUsd":{"type":"number","description":"BTC/USD price captured when the payment was created."},"btcPriceInCurrency":{"type":"number","description":"BTC price in the payment's `currency`, captured when the payment was created."},"currency":{"type":"string","description":"Fiat currency code (ISO 4217), e.g. `USD`."},"amount":{"type":"number","description":"Amount in the payment's fiat `currency`."},"currencySymbol":{"anyOf":[{"type":"string"},{"not":{}}],"description":"Display symbol of the currency, e.g. `$`."},"onChain":{"anyOf":[{"type":"object","properties":{"tx":{"type":"string","description":"On-chain Bitcoin transaction id (hex)."},"amountSats":{"type":"number","description":"Amount in satoshis."},"feeSats":{"type":"number","description":"Network fee for the transaction, in satoshis."},"createdAt":{"type":"integer","minimum":0,"description":"Creation time as a Unix timestamp (seconds)."}},"required":["tx","amountSats","feeSats","createdAt"],"additionalProperties":false},{"type":"null"}]}},"required":["paymentId","paymentTxId","status","storeId","storeName","posTerminalId","posTerminalLabel","posTerminalLocation","amountSats","description","createdAt","btcPriceInUsd","btcPriceInCurrency","currency","amount","onChain"],"additionalProperties":false}},"totalCount":{"type":"number","description":"Total number of records matching the filters."},"totals":{"type":"object","properties":{"paymentsCount":{"type":"number"},"grossAmount":{"type":"number"},"grossSats":{"type":"number"},"avgTicket":{"type":"number"},"currency":{"type":"string","description":"Fiat currency code (ISO 4217), e.g. `USD`."}},"required":["paymentsCount","grossAmount","grossSats","avgTicket","currency"],"additionalProperties":false}},"required":["items","totalCount","totals"],"additionalProperties":false}},"required":["$case","success"],"additionalProperties":false}},"required":["id","result"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"500":{"description":"Error response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"statusCode":{"type":"number","description":"Numeric error status code."},"description":{"type":"string","description":"Human-readable description."},"statusMessage":{"type":"string","description":"Short machine-readable error message."}},"required":["statusCode","description","statusMessage"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}}}}}}} ``` ## Aggregated report > Aggregates payments over a \`dateRange\` bucketed by \`groupBy\`, with optional \`filters\` (\`storeIds\`, \`posIds\`, \`currency\`) and a \`metrics\` selector (defaults to count and gross); returns the resulting \`groups\`. ```json {"openapi":"3.1.0","info":{"title":"GoBTC Pay Merchant Account API","version":"1.45.2"},"tags":[{"name":"Reports","description":"Sales summaries, transaction and aggregated reports, and async exports."}],"servers":[{"url":"https://api.gobtcpay.com/public/api/v1.1"}],"security":[{"merchantAuth":[]}],"components":{"securitySchemes":{"merchantAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Merchant dashboard access token obtained from `/merchant/auth/login` (or the OAuth / passkey / 2FA login flows). Send it as `Authorization: Bearer `. Refresh it via `/merchant/auth/refresh` when it expires."}}},"paths":{"/merchant/reports/aggregated":{"post":{"summary":"Aggregated report","description":"Aggregates payments over a `dateRange` bucketed by `groupBy`, with optional `filters` (`storeIds`, `posIds`, `currency`) and a `metrics` selector (defaults to count and gross); returns the resulting `groups`.","tags":["Reports"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"dateRange":{"type":"object","properties":{"start":{"type":"integer","minimum":0,"description":"UnixTime (seconds since epoch)"},"end":{"type":"integer","minimum":0,"description":"UnixTime (seconds since epoch)"}},"required":["start","end"],"additionalProperties":false},"groupBy":{"type":"string","enum":["day","week","month","store","pos","currency","status"]},"filters":{"type":"object","properties":{"storeIds":{"type":"array","items":{"type":"string"}},"posIds":{"type":"array","items":{"type":"string"}},"currency":{"type":"string","description":"Fiat currency code (ISO 4217), e.g. `USD`."}},"additionalProperties":false},"metrics":{"type":"array","items":{"type":"string"}}},"required":["dateRange","groupBy"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"result":{"type":"object","properties":{"$case":{"type":"string","const":"success"},"success":{"type":"object","properties":{"groups":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string","description":"Human-readable label for the POS terminal (optional)."},"paymentsCount":{"type":"number"},"grossAmount":{"type":"number"},"grossSats":{"type":"number"}},"required":["key","label","paymentsCount","grossAmount","grossSats"],"additionalProperties":false}}},"required":["groups"],"additionalProperties":false}},"required":["$case","success"],"additionalProperties":false}},"required":["id","result"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"500":{"description":"Error response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"statusCode":{"type":"number","description":"Numeric error status code."},"description":{"type":"string","description":"Human-readable description."},"statusMessage":{"type":"string","description":"Short machine-readable error message."}},"required":["statusCode","description","statusMessage"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}}}}}}} ``` ## Create export > Starts an asynchronous report export for the given \`type\`, \`format\`, \`dateRange\`, and \`filters\`, returning a \`reportJobId\` and initial \`status\`. Poll \`/merchant/reports/export/status\` with the \`reportJobId\` to retrieve the download URL once ready. ```json {"openapi":"3.1.0","info":{"title":"GoBTC Pay Merchant Account API","version":"1.45.2"},"tags":[{"name":"Reports","description":"Sales summaries, transaction and aggregated reports, and async exports."}],"servers":[{"url":"https://api.gobtcpay.com/public/api/v1.1"}],"security":[{"merchantAuth":[]}],"components":{"securitySchemes":{"merchantAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Merchant dashboard access token obtained from `/merchant/auth/login` (or the OAuth / passkey / 2FA login flows). Send it as `Authorization: Bearer `. Refresh it via `/merchant/auth/refresh` when it expires."}}},"paths":{"/merchant/reports/export":{"post":{"summary":"Create export","description":"Starts an asynchronous report export for the given `type`, `format`, `dateRange`, and `filters`, returning a `reportJobId` and initial `status`. Poll `/merchant/reports/export/status` with the `reportJobId` to retrieve the download URL once ready.","tags":["Reports"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["sales_summary","transaction_detail","aggregated"]},"format":{"type":"string","enum":["json","csv"]},"dateRange":{"type":"object","properties":{"start":{"type":"integer","minimum":0,"description":"UnixTime (seconds since epoch)"},"end":{"type":"integer","minimum":0,"description":"UnixTime (seconds since epoch)"}},"required":["start","end"],"additionalProperties":false},"filters":{}},"required":["type","format","dateRange"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"result":{"type":"object","properties":{"$case":{"type":"string","const":"success"},"success":{"type":"object","properties":{"reportJobId":{"type":"string"},"status":{"type":"string","enum":["pending","processing","ready","failed"],"description":"Current status. Payments: `initiated` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`."}},"required":["reportJobId","status"],"additionalProperties":false}},"required":["$case","success"],"additionalProperties":false}},"required":["id","result"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"500":{"description":"Error response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"statusCode":{"type":"number","description":"Numeric error status code."},"description":{"type":"string","description":"Human-readable description."},"statusMessage":{"type":"string","description":"Short machine-readable error message."}},"required":["statusCode","description","statusMessage"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}}}}}}} ``` ## Export status > Polls an export job by \`reportJobId\` and returns its \`status\`, plus a \`downloadUrl\` and \`expiresAt\` that are populated once the job is \`ready\` (both null while still processing). ```json {"openapi":"3.1.0","info":{"title":"GoBTC Pay Merchant Account API","version":"1.45.2"},"tags":[{"name":"Reports","description":"Sales summaries, transaction and aggregated reports, and async exports."}],"servers":[{"url":"https://api.gobtcpay.com/public/api/v1.1"}],"security":[{"merchantAuth":[]}],"components":{"securitySchemes":{"merchantAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Merchant dashboard access token obtained from `/merchant/auth/login` (or the OAuth / passkey / 2FA login flows). Send it as `Authorization: Bearer `. Refresh it via `/merchant/auth/refresh` when it expires."}}},"paths":{"/merchant/reports/export/status":{"post":{"summary":"Export status","description":"Polls an export job by `reportJobId` and returns its `status`, plus a `downloadUrl` and `expiresAt` that are populated once the job is `ready` (both null while still processing).","tags":["Reports"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reportJobId":{"type":"string"}},"required":["reportJobId"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"result":{"type":"object","properties":{"$case":{"type":"string","const":"success"},"success":{"type":"object","properties":{"status":{"type":"string","enum":["pending","processing","ready","failed"],"description":"Current status. Payments: `initiated` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`."},"downloadUrl":{"type":["string","null"]},"expiresAt":{"anyOf":[{"type":"integer","minimum":0,"description":"UnixTime (seconds since epoch)"},{"type":"null"}],"description":"Expiry time as a Unix timestamp (seconds)."}},"required":["status","downloadUrl","expiresAt"],"additionalProperties":false}},"required":["$case","success"],"additionalProperties":false}},"required":["id","result"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"500":{"description":"Error response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"statusCode":{"type":"number","description":"Numeric error status code."},"description":{"type":"string","description":"Human-readable description."},"statusMessage":{"type":"string","description":"Short machine-readable error message."}},"required":["statusCode","description","statusMessage"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}}}}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.gobtcpay.com/api-reference/merchant-api/reports.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.