# Events

> Retrieve events that record every notable change in your VINR account.

An event is created whenever something notable changes in your VINR account — a payment succeeds, an
invoice is paid, a subscription renews. Events are read-only; use
[webhook endpoints](/docs/api-reference/webhook-endpoints) to receive them in real time rather than
polling this API.

> **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 event object

- **id** `string` — Unique identifier for the event, e.g. `evt_9Bz1kWpA`.
- **type** `string` — The event type, e.g. `payment.succeeded` or `invoice.paid`. Used as the routing key in webhook
  endpoint subscriptions.
- **data** `object` — Container for the resource snapshot at the time the event was created.
  - **object** `object` — A full snapshot of the affected resource (e.g. the payment object). The shape matches the
    resource's normal retrieve response.
- **created** `timestamp` — Unix timestamp of when the event was created.

## Retrieve an event

`GET /v1/events/{id}`

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

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

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

const event = await vinr.events.retrieve('evt_9Bz1kWpA');
```

```python
import vinr

event = vinr.Event.retrieve("evt_9Bz1kWpA")
```

```ruby
event = Vinr::Event.retrieve("evt_9Bz1kWpA")
```

```json
{
"id": "evt_9Bz1kWpA",
"type": "payment.succeeded",
"data": {
  "object": {
    "id": "pay_3Nx8a2Lk",
    "amount": 5000,
    "currency": "EUR",
    "status": "succeeded",
    "customer": "cust_8aZ2",
    "created": 1716300000
  }
},
"created": 1716300001
}
```

## List events

Returns a list of events, optionally filtered by type or creation date. Results are sorted newest
first. Use `created.gte` to page forward from a known timestamp rather than polling for the latest.

`GET /v1/events`

```bash
curl "https://api.vinr.com/v1/events?type=payment.succeeded&created.gte=1716300000&limit=5" \
-H "X-Api-Key: $VINR_SECRET_KEY"
```

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

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

const events = await vinr.events.list({
type: 'payment.succeeded',
'created.gte': 1716300000,
limit: 5,
});
```

```python
import vinr

events = vinr.Event.list(
  type="payment.succeeded",
  created={"gte": 1716300000},
  limit=5,
)
```

```ruby
events = Vinr::Event.list(
type: 'payment.succeeded',
created: { gte: 1716300000 },
limit: 5,
)
```

```json
{
"object": "list",
"data": [
  {
    "id": "evt_9Bz1kWpA",
    "type": "payment.succeeded",
    "data": {
      "object": {
        "id": "pay_3Nx8a2Lk",
        "amount": 5000,
        "currency": "EUR",
        "status": "succeeded"
      }
    },
    "created": 1716300001
  }
],
"has_more": false
}
```