# Store Credit

> Create, retrieve, update, and list store credit balances for customers.

Store credit is a balance of credit applied to a customer's future purchases. When a customer has
available store credit, it can be automatically applied at checkout to reduce the amount charged to
their payment method.

> **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 store credit object

- **id** `string` — Unique identifier for the store credit record, e.g. `sc_4Bk9mQ`.
- **customer** `object` (expandable) — The customer this store credit belongs to. Expand to retrieve the full customer object.
  - **id** `string` — Customer identifier, e.g. `cust_8aZ2`.
  - **email** `string` — Email address on the customer record.
- **amount** `integer` — Original credit amount issued, in the smallest currency unit (e.g. cents).
- **currency** `string` — Three-letter [ISO currency code](/docs/payments/payment-methods), e.g. `USD`.
- **balance\_remaining** `integer` — Amount of credit still available to redeem, in the smallest currency unit.
- **expires\_at** `integer` — Unix timestamp at which this credit expires and can no longer be redeemed, or `null` if it does
  not expire.
- **created** `integer` — Unix timestamp when this store credit record was created.

## Create store credit

Issue store credit to a customer. Specify an amount, currency, and optionally an expiry date.

`POST /v1/store-credit`

```bash
curl -X POST https://api.vinr.com/v1/store-credit \
-H "X-Api-Key: $VINR_SECRET_KEY" \
-d customer=cust_8aZ2 \
-d amount=1000 \
-d currency=USD \
-d expires_at=1748736000
```

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

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

const credit = await vinr.storeCredit.create({
customer: 'cust_8aZ2',
amount: 1000,
currency: 'USD',
expires_at: 1748736000,
});
```

```python
import vinr

credit = vinr.StoreCredit.create(
  customer="cust_8aZ2",
  amount=1000,
  currency="USD",
  expires_at=1748736000,
)
```

```ruby
credit = Vinr::StoreCredit.create(
customer: 'cust_8aZ2',
amount: 1000,
currency: 'USD',
expires_at: 1748736000,
)
```

```json
{
"id": "sc_4Bk9mQ",
"customer": "cust_8aZ2",
"amount": 1000,
"currency": "USD",
"balance_remaining": 1000,
"expires_at": 1748736000,
"created": 1716300000
}
```

## Retrieve store credit

Fetch a store credit record by its ID.

`GET /v1/store-credit/{id}`

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

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

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

const credit = await vinr.storeCredit.retrieve('sc_4Bk9mQ');
```

```python
import vinr

credit = vinr.StoreCredit.retrieve("sc_4Bk9mQ")
```

```ruby
credit = Vinr::StoreCredit.retrieve('sc_4Bk9mQ')
```

```json
{
"id": "sc_4Bk9mQ",
"customer": "cust_8aZ2",
"amount": 1000,
"currency": "USD",
"balance_remaining": 750,
"expires_at": 1748736000,
"created": 1716300000
}
```

## Update store credit

Update the expiry date on an existing store credit record. The `balance_remaining` is read-only and
adjusted automatically as the credit is applied to purchases.

| Parameter    | Type    | Description                                                    |
| ------------ | ------- | -------------------------------------------------------------- |
| `expires_at` | integer | New Unix timestamp for expiry. Set to `null` to remove expiry. |

`POST /v1/store-credit/{id}`

```bash
curl -X POST https://api.vinr.com/v1/store-credit/sc_4Bk9mQ \
-H "X-Api-Key: $VINR_SECRET_KEY" \
-d expires_at=1751328000
```

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

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

const credit = await vinr.storeCredit.update('sc_4Bk9mQ', {
expires_at: 1751328000,
});
```

```python
import vinr

credit = vinr.StoreCredit.modify(
  "sc_4Bk9mQ",
  expires_at=1751328000,
)
```

```ruby
credit = Vinr::StoreCredit.update(
'sc_4Bk9mQ',
expires_at: 1751328000,
)
```

```json
{
"id": "sc_4Bk9mQ",
"customer": "cust_8aZ2",
"amount": 1000,
"currency": "USD",
"balance_remaining": 750,
"expires_at": 1751328000,
"created": 1716300000
}
```

## List store credit

Returns a paginated list of store credit records. Use the `customer` filter to scope results to a
single customer.

| Parameter  | Type    | Description                                           |
| ---------- | ------- | ----------------------------------------------------- |
| `customer` | string  | Filter records by customer ID.                        |
| `limit`    | integer | Number of results to return. Default `10`, max `100`. |

`GET /v1/store-credit`

```bash
curl "https://api.vinr.com/v1/store-credit?customer=cust_8aZ2&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 credits = await vinr.storeCredit.list({
customer: 'cust_8aZ2',
limit: 10,
});
```

```python
import vinr

credits = vinr.StoreCredit.list(
  customer="cust_8aZ2",
  limit=10,
)
```

```ruby
credits = Vinr::StoreCredit.list(
customer: 'cust_8aZ2',
limit: 10,
)
```

```json
{
"object": "list",
"data": [
  {
    "id": "sc_4Bk9mQ",
    "customer": "cust_8aZ2",
    "amount": 1000,
    "currency": "USD",
    "balance_remaining": 750,
    "expires_at": 1748736000,
    "created": 1716300000
  }
],
"has_more": false
}
```

## Related events

`store_credit.created` and `store_credit.updated`. See [Events](/docs/api-reference/events).