# Billing portal sessions

> Create short-lived authenticated sessions for the VINR hosted billing portal.

A billing portal session creates a short-lived, one-time URL that takes a customer to the VINR
hosted billing portal. From there they can update their subscription plan, change their payment
method, and view past invoices — without you building any of that UI yourself.

> **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 billing portal session object

- **id** `string` — Unique identifier for the session, e.g. `bps_2Fy6rNxQ`.
- **customer** `string` (expandable) — The customer (`cust_`) this session was created for. Expand to retrieve the full customer
  object.
- **url** `string` — The one-time portal URL to redirect the customer to. This URL expires after 24 hours and can
  only be visited once.
- **return\_url** `string` — The URL the customer is redirected to after they finish in the portal or click the back link.
- **created** `timestamp` — Unix timestamp of when the session was created.

## Create a billing portal session

Pass the customer ID and a `return_url` where VINR should send the customer when they leave the
portal. Redirect the customer to the returned `url` immediately — it expires after 24 hours.

`POST /v1/billing-portal/sessions`

```bash
curl -X POST https://api.vinr.com/v1/billing-portal/sessions \
-H "X-Api-Key: $VINR_SECRET_KEY" \
-d customer=cust_8aZ2 \
-d return_url=https://example.com/account
```

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

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

const session = await vinr.billingPortal.sessions.create({
customer: 'cust_8aZ2',
return_url: 'https://example.com/account',
});

// Redirect the customer
res.redirect(session.url);
```

```python
import vinr

session = vinr.billing_portal.Session.create(
  customer="cust_8aZ2",
  return_url="https://example.com/account",
)

# Redirect the customer to session.url
```

```ruby
session = Vinr::BillingPortal::Session.create(
customer: 'cust_8aZ2',
return_url: 'https://example.com/account',
)

# Redirect the customer to session.url
```

```json
{
"id": "bps_2Fy6rNxQ",
"customer": "cust_8aZ2",
"url": "https://billing.vinr.com/session/bps_2Fy6rNxQ/live_tok_abc123",
"return_url": "https://example.com/account",
"created": 1716300000
}
```