> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stablepayfi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List Bills

> List successfully generated bills for the current merchant by bill type and date.

List bills successfully generated for the current merchant, filtered by bill type and date, with pagination. The API Key identifies the merchant; no merchant ID is required.

<Note>
  `bill_date_from` and `bill_date_to` are required. The date range includes both endpoints and must not exceed **90 days**. Omit `bill_types` to query all bill types.
</Note>

## Authentication and Headers

Authenticate with a Bearer API Key and include the signing headers below. GET requests use an empty `requestBody`, so the signature payload is `{timestamp}.{nonce}.`. Compute HMAC-SHA256 with the merchant API Secret and encode the result as lowercase hex. See [Authentication and Signing](/en/api/getting-started#authentication-and-signing).

<ParamField header="Authorization" type="string" required>
  Bearer API Key in the format `Bearer sk_live_xxx`.
</ParamField>

<ParamField header="X-StablePay-Timestamp" type="string" required>
  Unix timestamp in seconds. It must be within 5 minutes of the server time.
</ParamField>

<ParamField header="X-StablePay-Nonce" type="string" required>
  Random string for replay protection, 16–64 characters long. Use a new UUID for each request. Minimum length: 16 characters. Maximum length: 64 characters.
</ParamField>

<ParamField header="X-StablePay-Signature" type="string" required>
  HMAC-SHA256 of `{timestamp}.{nonce}.{requestBody}` using the merchant API Secret, encoded as lowercase hex. For GET requests, `requestBody` is an empty string.
</ParamField>

## Query Parameters

<ParamField query="bill_types" type="string[]">
  Optional list of bill type identifiers separated by commas, such as `payment,payment_fee`. Omit this parameter to query all bill types. At least 1 item.

  Stable bill type identifier maintained by BillProd. Current values: `payment` for online payments, `payment_fee` for payment fees, `subscription` for subscription payments, `subscription_period` for subscription periods, `subscription_fee` for subscription fees, `payout` for payouts, `payout_fee` for payout fees, and `capital_flow` for fund movements. New string values may be added; clients must handle unknown values. Pattern: `^[a-z][a-z0-9_]{0,63}$`.
</ParamField>

<ParamField query="bill_date_from" type="string" required>
  Start date for the bill query in `YYYY-MM-DD` format, inclusive. Format: `date`.
</ParamField>

<ParamField query="bill_date_to" type="string" required>
  End date for the bill query in `YYYY-MM-DD` format, inclusive. The date range must not exceed 90 days. Format: `date`.
</ParamField>

<ParamField query="page" type="integer" default={1}>
  Page number, starting at 1. Defaults to 1. Minimum: 1.
</ParamField>

<ParamField query="page_size" type="integer" default={20}>
  Number of bills per page, from 1 to 100. Defaults to 20. Minimum: 1. Maximum: 100.
</ParamField>

## Success Response

HTTP `200`, `application/json`. Query successful. If no bills match, `data` is an empty array.

<ResponseField name="data" type="object[]" required>
  Bills on the current page.

  <Expandable title="Fields">
    <ResponseField name="bill_id" type="string" required>
      Bill ID, returned as a string to avoid integer precision loss in clients. Pattern: `^[0-9]+$`.
    </ResponseField>

    <ResponseField name="bill_type" type="string" required>
      Stable bill type identifier maintained by BillProd. Current values: `payment` for online payments, `payment_fee` for payment fees, `subscription` for subscription payments, `subscription_period` for subscription periods, `subscription_fee` for subscription fees, `payout` for payouts, `payout_fee` for payout fees, and `capital_flow` for fund movements. New string values may be added; clients must handle unknown values. Pattern: `^[a-z][a-z0-9_]{0,63}$`.
    </ResponseField>

    <ResponseField name="bill_date" type="string" required>
      Bill date. Format: `date`.
    </ResponseField>

    <ResponseField name="currency" type="string" required>
      Bill currency.
    </ResponseField>

    <ResponseField name="transaction_count" type="integer" required>
      Number of transaction records in the bill. Format: `int64`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="total_count" type="integer" required>
  Total number of bills matching the filters. Format: `int64`. Minimum: 0.
</ResponseField>

<ResponseField name="page" type="integer" required>
  Current page number. Minimum: 1.
</ResponseField>

<ResponseField name="page_size" type="integer" required>
  Number of bills per page. Minimum: 1. Maximum: 100.
</ResponseField>

## Error Responses

| HTTP Status | Description |
| - | - |
| 400 | Invalid request parameters. |
| 401 | Authentication failed. |
| 503 | BillProd or another dependent service is temporarily unavailable. |

### Service Error Structure

<ResponseField name="error" type="object" required>
  <Expandable title="Fields">
    <ResponseField name="code" type="string" required>
      Error code, such as `invalid_parameter`, `resource_not_found`, `historical_report_unavailable`, `report_incomplete`, or `service_unavailable`.
    </ResponseField>

    <ResponseField name="message" type="string" required>
      Error message.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="request_id" type="string" required>
  Request ID.
</ResponseField>

<ResponseField name="timestamp" type="integer" required>
  Time of the error, as a Unix timestamp in seconds. Format: `int64`.
</ResponseField>

### Gateway Authentication Error Structure

Before a request reaches PaymentProd, the API gateway may return an HTTP `401` response with the following structure.

<ResponseField name="status" type="string" required>
  Value: `error`.
</ResponseField>

<ResponseField name="error" type="string" required>
  Reason for the authentication failure.
</ResponseField>

Next, use the returned `bill_id` to [get a bill download URL](/en/api/bills/get-download-url).

<RequestExample>
  ```bash cURL theme={"system"}
  TIMESTAMP=$(date +%s)
  NONCE=$(uuidgen)
  SIGNATURE=$(printf '%s' "${TIMESTAMP}.${NONCE}." | openssl dgst -sha256 -hmac "${SECRET_KEY}" | awk '{print $NF}')

  curl --get 'https://api.stablepay.co/api/v1/bills' \
    --data-urlencode 'bill_date_from=2026-09-01' \
    --data-urlencode 'bill_date_to=2026-09-30' \
    --data-urlencode 'bill_types=payment,payment_fee' \
    --data-urlencode 'page=1' \
    --data-urlencode 'page_size=20' \
    -H "Authorization: Bearer ${API_KEY}" \
    -H "X-StablePay-Timestamp: ${TIMESTAMP}" \
    -H "X-StablePay-Nonce: ${NONCE}" \
    -H "X-StablePay-Signature: ${SIGNATURE}"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 (Example) theme={"system"}
  {
    "data": [
      {
        "bill_id": "1234567890",
        "bill_type": "payment",
        "bill_date": "2026-09-01",
        "currency": "USD",
        "transaction_count": 10
      }
    ],
    "total_count": 1,
    "page": 1,
    "page_size": 20
  }
  ```

  ```json Service Error (Example) theme={"system"}
  {
    "error": {
      "code": "invalid_parameter",
      "message": "Invalid request parameters"
    },
    "request_id": "req_example",
    "timestamp": 1790812800
  }
  ```

  ```json Gateway Authentication Error (Example) theme={"system"}
  {
    "status": "error",
    "error": "Authentication failed"
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.