---
title: "Get transaction history"
method: GET
path: "/credits/transactions"
tags: ["Credits"]
---

# Get transaction history

`GET /credits/transactions`

## Request

- Base URL: `https://api.faireplace.com/api`
- URL: `https://api.faireplace.com/api/credits/transactions`
- Auth: HTTP bearer

Retrieves the credit transaction history of the authenticated user with pagination.

## Pagination

Transactions are returned with pagination:
- **limit**: Maximum number of transactions to return (default: 50, max: 100)
- **offset**: Number of transactions to skip (default: 0)

Transactions are sorted by **creation date descending** (most recent first).

## Transaction Types

Transactions can be of different types:
- `purchase`: Credit purchase via Stripe
- `consumption`: Credit consumption for a payment
- `expiration`: Credit expiration (if applicable)
- `refund`: Credit refund
- `adjustment`: Manual adjustment by an administrator

## Amount Format

Amounts are in cents:
- **Positive** amount for purchases and additions
- **Negative** amount for consumptions

## Multi-Tenant Isolation

The returned transactions are automatically filtered by:
- `tenant_id` extracted from the JWT
- `user_id` extracted from the JWT (claim `sub`)

A user can only see their own transactions, and only within their tenant.

## Usage Example

```bash
# Retrieve the first 20 transactions
curl -X GET "https://api.faireplace.com/v1/credits/transactions?limit=20&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Retrieve the next transactions (pagination)
curl -X GET "https://api.faireplace.com/v1/credits/transactions?limit=20&offset=20" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Response**:
```json
{
  "transactions": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "amount": 1000,
      "transaction_type": "purchase",
      "reason": "Credit purchase via Stripe Checkout Session cs_test_123",
      "balance_before": 2000,
      "balance_after": 3000,
      "created_at": "2026-01-28T10:30:00Z"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "amount": -2990,
      "transaction_type": "consumption",
      "reason": "Consumption for lease signing lease_789",
      "balance_before": 5000,
      "balance_after": 2010,
      "created_at": "2026-01-27T15:20:00Z"
    }
  ],
  "total": 2,
  "limit": 20,
  "offset": 0
}
```

## Query parameters

- `limit` integer
- `offset` integer

## Response `200`

Transaction history retrieved successfully.

Always returns an array (empty if the user has never had transactions).

- CreditTransactionsResponse: Response containing the list of credit transactions with pagination.
  - `transactions` CreditTransaction[], required: List of transactions, sorted by creation date descending (most recent first).
    - `id` string, uuid, required: Unique transaction identifier.
    - `amount` integer, required: Transaction amount in cents. **Convention**: - Positive amount for purchases and additions - Negative amount for consumptions
    - `transaction_type` 'purchase' | 'consumption' | 'expiration' | 'refund' | 'adjustment', required: Credit transaction type. The different types allow tracking the origin and nature of each credit movement.
    - `reason` string, nullable: Reason or description of the transaction. **Examples**: - "Credit purchase via Stripe Checkout Session cs_test_123 (event: evt_test_456)" - "Consumption for lease signing lease_789" - "Manual adjustment by administrator"
    - `balance_before` integer, required: Balance before the transaction (in cents).
    - `balance_after` integer, required: Balance after the transaction (in cents).
    - `created_at` string, date-time, required: Date and time of the transaction creation (ISO 8601).
  - `total` integer, required: Total number of transactions returned in this response. **Note**: This is not the total number of user transactions, but only the count returned in this page.
  - `limit` integer, required: Maximum number of requested transactions. Default value: `50` Maximum: `100`
  - `offset` integer, required: Offset for pagination (number of transactions to skip). Default value: `0`

## Other responses

- `400`: Invalid pagination parameters. **Possible causes**: - `limit` > 100 - `limit` < 1 - `offset` < 0
- `401`: Unauthorized
- `403`: Forbidden
- `500`: Internal Server Error

---

[API](https://skmtc.dev/faireplace/apis/faireplace-property-management-api.md) · [All operations](https://skmtc.dev/faireplace/apis/faireplace-property-management-api/llms.txt) · [OpenAPI document](https://skmtc.dev/faireplace/apis/faireplace-property-management-api/revisions/69de39762919?raw)