# Points Transactions

> Create, retrieve, and list credits and debits to a loyalty account's points balance.

A points transaction records a credit or debit to a loyalty account's balance. Credits increase the
balance (e.g. from a qualifying purchase); debits decrease it (e.g. when redeeming a reward).

> **Illustrative content.** Hand-authored to demonstrate the Standard/Advanced pattern; the production
> page will be generated from the VINR OpenAPI spec (roadmap item #1). Field names are representative.

## The points transaction object

- **id** `string` — Unique identifier for the transaction, e.g. `pt_7Rm1cW`.
- **loyalty\_account** `object` (expandable) — The loyalty account whose balance was affected. Expand to retrieve the full object.
  - **id** `string` — Loyalty account identifier, e.g. `la_4Kp9bQ`.
  - **points\_balance** `integer` — Balance after this transaction was applied.
- **amount** `integer` — Number of points credited or debited. Always positive; direction is indicated by `type`.
- **type** `enum` — Either `credit` (points added) or `debit` (points removed).
- **points\_after** `integer` — The loyalty account's points balance immediately after this transaction.
- **reason** `string` — Human-readable description of why the transaction occurred, e.g. `Purchase earn` or `Reward redemption`.
- **created** `integer` — Unix timestamp of when the transaction was created.

## Create a points transaction

Manually credit or debit a loyalty account. Most credits are created automatically by the engine
when an [earning rule](/docs/api-reference/earning-rules) fires; use this endpoint for manual
adjustments or custom integrations.

`POST /v1/points-transactions`

```bash
curl -X POST https://api.vinr.com/v1/points-transactions \
-H "X-Api-Key: $VINR_SECRET_KEY" \
-d loyalty_account=la_4Kp9bQ \
-d amount=200 \
-d type=credit \
-d reason="Bonus promotion"
```

```js
import { Vinr } from '@vinr/sdk';

const vinr = new Vinr({ secretKey: process.env.VINR_SECRET_KEY });

const transaction = await vinr.pointsTransactions.create({
loyalty_account: 'la_4Kp9bQ',
amount: 200,
type: 'credit',
reason: 'Bonus promotion',
});
```

```python
import vinr

transaction = vinr.PointsTransaction.create(
  loyalty_account="la_4Kp9bQ",
  amount=200,
  type="credit",
  reason="Bonus promotion",
)
```

```ruby
transaction = Vinr::PointsTransaction.create(
loyalty_account: 'la_4Kp9bQ',
amount: 200,
type: 'credit',
reason: 'Bonus promotion',
)
```

```json
{
"id": "pt_7Rm1cW",
"loyalty_account": "la_4Kp9bQ",
"amount": 200,
"type": "credit",
"points_after": 1450,
"reason": "Bonus promotion",
"created": 1716300000
}
```

## Retrieve a points transaction

Fetch a single points transaction by its ID.

`GET /v1/points-transactions/{id}`

```bash
curl https://api.vinr.com/v1/points-transactions/pt_7Rm1cW \
-H "X-Api-Key: $VINR_SECRET_KEY"
```

```js
import { Vinr } from '@vinr/sdk';

const vinr = new Vinr({ secretKey: process.env.VINR_SECRET_KEY });

const transaction = await vinr.pointsTransactions.retrieve('pt_7Rm1cW');
```

```python
import vinr

transaction = vinr.PointsTransaction.retrieve("pt_7Rm1cW")
```

```ruby
transaction = Vinr::PointsTransaction.retrieve('pt_7Rm1cW')
```

```json
{
"id": "pt_7Rm1cW",
"loyalty_account": "la_4Kp9bQ",
"amount": 200,
"type": "credit",
"points_after": 1450,
"reason": "Bonus promotion",
"created": 1716300000
}
```

## List points transactions

Returns a paginated list of points transactions, newest first. Filter by `loyalty_account` and/or
`type` to narrow results.

| Parameter         | Type    | Description                                           |
| ----------------- | ------- | ----------------------------------------------------- |
| `loyalty_account` | string  | Filter to transactions on a specific loyalty account. |
| `type`            | enum    | `credit` or `debit`. Omit to return both.             |
| `limit`           | integer | Number of results to return. Default `10`, max `100`. |

`GET /v1/points-transactions`

```bash
curl "https://api.vinr.com/v1/points-transactions?loyalty_account=la_4Kp9bQ&type=credit&limit=10" \
-H "X-Api-Key: $VINR_SECRET_KEY"
```

```js
import { Vinr } from '@vinr/sdk';

const vinr = new Vinr({ secretKey: process.env.VINR_SECRET_KEY });

const transactions = await vinr.pointsTransactions.list({
loyalty_account: 'la_4Kp9bQ',
type: 'credit',
limit: 10,
});
```

```python
import vinr

transactions = vinr.PointsTransaction.list(
  loyalty_account="la_4Kp9bQ",
  type="credit",
  limit=10,
)
```

```ruby
transactions = Vinr::PointsTransaction.list(
loyalty_account: 'la_4Kp9bQ',
type: 'credit',
limit: 10,
)
```

```json
{
"object": "list",
"data": [
  {
    "id": "pt_7Rm1cW",
    "loyalty_account": "la_4Kp9bQ",
    "amount": 200,
    "type": "credit",
    "points_after": 1450,
    "reason": "Bonus promotion",
    "created": 1716300000
  }
],
"has_more": false
}
```

## Related events

`points_transaction.created`. See [Events](/docs/api-reference/events).