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

# Response Format

> Envelope structure, pagination, money formatting, and timestamps

## Response envelope

Every API response uses a consistent envelope:

```json theme={null}
{
  "data": { ... },
  "meta": {
    "request_id": "req_abc123",
    "api_version": "v2",
    "source": "bigquery",
    "as_of": "2026-02-09T04:00:00Z"
  },
  "errors": []
}
```

| Field              | Type            | Description                                          |
| ------------------ | --------------- | ---------------------------------------------------- |
| `data`             | object or array | The response payload. `null` on errors.              |
| `meta.request_id`  | string          | Unique request identifier for debugging              |
| `meta.api_version` | string          | Always `"v2"`                                        |
| `meta.source`      | string          | Data source (`risecrm`, `bigquery`, `nmi`, etc.)     |
| `meta.as_of`       | string          | ISO-8601 timestamp of data freshness                 |
| `errors`           | array           | Empty on success. Contains error objects on failure. |

## Pagination

List endpoints return paginated results with metadata:

```json theme={null}
{
  "data": [ ... ],
  "meta": {
    "request_id": "req_abc123",
    "api_version": "v2",
    "pagination": {
      "page": 1,
      "page_size": 50,
      "total_count": 6153,
      "total_pages": 124
    }
  }
}
```

### Parameters

| Parameter   | Default | Max   | Description             |
| ----------- | ------- | ----- | ----------------------- |
| `page`      | `1`     | —     | Page number (1-indexed) |
| `page_size` | `25`    | `200` | Items per page          |

### Iterating pages

<CodeGroup>
  ```python Python theme={null}
  import requests

  url = "https://modulate.aurorapayments.net/api/partner/merchants"
  headers = {"X-Partner-API-Key": "pk_live_YOUR_KEY_HERE"}
  page = 1

  while True:
      resp = requests.get(url, headers=headers, params={"page": page, "page_size": 100})
      result = resp.json()
      merchants = result["data"]

      for merchant in merchants:
          process(merchant)

      pagination = result["meta"]["pagination"]
      if page >= pagination["total_pages"]:
          break
      page += 1
  ```

  ```javascript Node.js theme={null}
  const headers = { "X-Partner-API-Key": "pk_live_YOUR_KEY_HERE" };
  let page = 1;

  while (true) {
    const resp = await fetch(
      `https://modulate.aurorapayments.net/api/partner/merchants?page=${page}&page_size=100`,
      { headers }
    );
    const { data: merchants, meta } = await resp.json();

    for (const merchant of merchants) {
      process(merchant);
    }

    if (page >= meta.pagination.total_pages) break;
    page++;
  }
  ```
</CodeGroup>

## Money formatting

All monetary values are returned as **decimal strings** to avoid IEEE 754 floating-point precision issues:

```json theme={null}
{
  "volume": "1045230.56",
  "total_fees": "12543.89",
  "payout": "4532.10"
}
```

<Warning>
  Never parse monetary values as floats. Use decimal types (`Decimal` in Python, `BigDecimal` in Java, string math in JavaScript).
</Warning>

## Timestamps

All timestamps use ISO-8601 format in UTC:

```
2026-02-09T04:00:00Z
```

The `meta.as_of` field tells you when the underlying data was last refreshed. See [Data Freshness](/data-freshness) for per-endpoint details.

## Incremental sync

Most list endpoints accept an `updated_since` parameter for incremental sync:

```
GET /merchants?updated_since=2026-01-15T00:00:00Z
```

This returns only records modified after the given timestamp. See the [Sync Merchants](/guides/sync-merchants) guide for a full implementation pattern.