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

# Credits and billing

> Read balances, inspect billing history, create checkout sessions, and reconcile completed credit purchases.

## Per-event pricing

Jobs are billed per event in **credits** (1 credit = 1 USD). The table below lists the default unit prices. Your account's active pricing rules at run time are authoritative — the [estimate endpoint](/docs/api-reference/jobs) returns the exact `unit_prices` used for a given job.

| Event             | Default price | Charged                                                                                                             |
| ----------------- | ------------- | ------------------------------------------------------------------------------------------------------------------- |
| `job_start`       | `0.007`       | Once per job                                                                                                        |
| `place_scraped`   | `0.003`       | Per place written to your results                                                                                   |
| `contact_details` | `0.002`       | Per place, when `include_emails` is enabled                                                                         |
| `review`          | `0.0005`      | Per review collected                                                                                                |
| `image`           | `0.0005`      | Per image collected                                                                                                 |
| `filters_applied` | `0.001`       | Per matching place, when a `no_website`/`has_website` [`website_filter`](/docs/api-reference/jobs#website-filter) is set |

Charges are computed on the data **actually stored**. A `website_filter` drops non-matching businesses before they are written, so it also removes their `place_scraped`, `contact_details`, `review`, and `image` charges — you pay only for matching leads plus the `0.001` per-match filter fee.

## `GET /api/v1/credits/balance`

Return the authenticated user's current credit balance.

### Example response

```json theme={null}
{
  "user_id": "user_123",
  "credit_balance": "25",
  "total_credits_purchased": "100"
}
```

<Note>
  Credit values are returned as decimal strings (e.g., `"25.123456"`) to preserve precision. Parse them as decimals, not as floating-point numbers.
</Note>

## `GET /api/v1/credits/history`

Return paginated credit transaction history.

### Query parameters

| Parameter | Type    | Default | Notes                      |
| --------- | ------- | ------- | -------------------------- |
| `page`    | integer | `1`     | Must be positive           |
| `limit`   | integer | `50`    | Max `100`                  |
| `type`    | string  | empty   | Filter by transaction type |

Common transaction types:

* `purchase`
* `consumption`
* `bonus`
* `refund`
* `adjustment`

In some edge cases you may also see `refund_deficit` or `deficit_paydown` in the response history.

### Example response

```json theme={null}
{
  "transactions": [
    {
      "id": "018efdf7-7fe1-7c42-b4e2-123456789abc",
      "type": "purchase",
      "amount": "25",
      "balance_before": "0",
      "balance_after": "25",
      "description": "Stripe checkout session",
      "reference_id": "cs_test_123",
      "reference_type": "stripe_checkout_session",
      "created_at": "2026-04-10T09:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 50,
  "has_more": false
}
```

## `POST /api/v1/credits/checkout-session`

Create a Stripe Checkout session to buy credits.

### Request body

```json theme={null}
{
  "credits": "25",
  "currency": "USD"
}
```

Rules:

* `credits` must be a whole positive integer
* Maximum `credits` per checkout session is `10000`
* `currency` currently supports `USD` only

### Success response

```json theme={null}
{
  "session_id": "cs_test_123",
  "url": "https://checkout.stripe.com/..."
}
```

Redirect the user to `url` to complete the purchase.

## `POST /api/v1/credits/reconcile`

Confirm a completed checkout session against the authenticated user.

### Request body

```json theme={null}
{
  "session_id": "cs_test_123"
}
```

Returns `204 No Content` on success.

Use this after the user returns from Stripe if you want to refresh credits immediately instead of waiting for normal background settlement.