Reports

Sales summaries, transaction and aggregated reports, and async exports.

Sales summary

POSThttps://api.gobtcpay.com/public/api/v1.2/merchant/reports/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).

Authorization: merchantAuth

Body required

application/json

dateRangeobjectrequired

filtersobject

Responses

idstringrequired

Example:3fa85f64-5717-4562-b3fc-2c963f66afa6

resultobjectrequired

POST /merchant/reports/sales-summary

cURL

curl -X POST "$BASE_URL/merchant/reports/sales-summary" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
  "dateRange": {
    "start": 1718012345,
    "end": 1718012345
  },
  "filters": {
    "storeIds": [
      "string"
    ],
    "posIds": [
      "string"
    ],
    "currency": "USD"
  }
}'

200 Successful response

JSON

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "result": {
    "$case": "success",
    "success": {
      "totals": {
        "paymentsCount": 0,
        "grossAmount": 10,
        "grossSats": "string",
        "avgTicket": 0,
        "currency": "USD"
      },
      "breakdown": [
        {
          "key": "string",
          "label": "Front desk",
          "paymentsCount": 0,
          "grossAmount": 10,
          "grossSats": "string"
        }
      ]
    }
  }
}

Transactions report

POSThttps://api.gobtcpay.com/public/api/v1.2/merchant/reports/transactions

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.

Authorization: merchantAuth

Body required

application/json

paginationobject

dateRangeobjectrequired

filtersobject

Responses

idstringrequired

Example:3fa85f64-5717-4562-b3fc-2c963f66afa6

resultobjectrequired

POST /merchant/reports/transactions

cURL

curl -X POST "$BASE_URL/merchant/reports/transactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
  "pagination": {
    "limit": 20,
    "skip": 0
  },
  "dateRange": {
    "start": 1718012345,
    "end": 1718012345
  },
  "filters": {
    "storeIds": [
      "string"
    ],
    "posIds": [
      "string"
    ],
    "status": [
      "initiated"
    ],
    "currency": "USD",
    "system": true
  }
}'

200 Successful response

JSON

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "result": {
    "$case": "success",
    "success": {
      "items": [
        {
          "paymentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "paymentTxId": "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b",
          "status": "success",
          "paymentStatus": "initiated",
          "storeId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "storeName": "string",
          "posTerminalId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "posTerminalLabel": "Front desk",
          "posTerminalLocation": "Lisbon, PT",
          "amountSats": "string",
          "description": "Order #1024",
          "createdAt": 1718012345,
          "btcPriceInUsd": 65000,
          "btcPriceInCurrency": 65000,
          "currency": "USD",
          "amount": 10,
          "currencySymbol": "$",
          "onChain": {
            "tx": null,
            "amountSats": null,
            "feeSats": null,
            "createdAt": null
          },
          "settlement": {
            "settledAt": null,
            "status": null,
            "platformFeeSats": null,
            "netSats": null,
            "payout": null
          }
        }
      ],
      "totalCount": 0,
      "totals": {
        "paymentsCount": 0,
        "grossAmount": 10,
        "grossSats": "string",
        "avgTicket": 0,
        "currency": "USD"
      }
    }
  }
}

Aggregated report

POSThttps://api.gobtcpay.com/public/api/v1.2/merchant/reports/aggregated

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.

Authorization: merchantAuth

Body required

application/json

dateRangeobjectrequired

groupByenumrequired

dayweekmonthstoreposcurrencystatus

Example:day

filtersobject

metricsstring[]

Responses

idstringrequired

Example:3fa85f64-5717-4562-b3fc-2c963f66afa6

resultobjectrequired

POST /merchant/reports/aggregated

cURL

curl -X POST "$BASE_URL/merchant/reports/aggregated" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
  "dateRange": {
    "start": 1718012345,
    "end": 1718012345
  },
  "groupBy": "day",
  "filters": {
    "storeIds": [
      "string"
    ],
    "posIds": [
      "string"
    ],
    "currency": "USD"
  },
  "metrics": [
    "string"
  ]
}'

200 Successful response

JSON

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "result": {
    "$case": "success",
    "success": {
      "groups": [
        {
          "key": "string",
          "label": "Front desk",
          "paymentsCount": 0,
          "grossAmount": 10,
          "grossSats": "string"
        }
      ]
    }
  }
}

Create export

POSThttps://api.gobtcpay.com/public/api/v1.2/merchant/reports/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.

Authorization: merchantAuth

Body required

application/json

typeenumrequired

sales_summarytransaction_detailaggregated

Example:sales_summary

formatenumrequired

jsoncsv

Example:json

dateRangeobjectrequired

filtersany

Responses

idstringrequired

Example:3fa85f64-5717-4562-b3fc-2c963f66afa6

resultobjectrequired

POST /merchant/reports/export

cURL

curl -X POST "$BASE_URL/merchant/reports/export" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
  "type": "sales_summary",
  "format": "json",
  "dateRange": {
    "start": 1718012345,
    "end": 1718012345
  },
  "filters": {}
}'

200 Successful response

JSON

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "result": {
    "$case": "success",
    "success": {
      "reportJobId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "status": "pending"
    }
  }
}

Export status

POSThttps://api.gobtcpay.com/public/api/v1.2/merchant/reports/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).

Authorization: merchantAuth

Body required

application/json

reportJobIdstringrequired

Example:3fa85f64-5717-4562-b3fc-2c963f66afa6

Responses

idstringrequired

Example:3fa85f64-5717-4562-b3fc-2c963f66afa6

resultobjectrequired

POST /merchant/reports/export/status

cURL

curl -X POST "$BASE_URL/merchant/reports/export/status" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
  "reportJobId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}'

200 Successful response

JSON

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "result": {
    "$case": "success",
    "success": {
      "status": "pending",
      "downloadUrl": "string",
      "expiresAt": 1718012345
    }
  }
}