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

# Subscriptions

> Create and manage subscriptions server-side.

## createSubscription

```typescript theme={null}
const subscription = await billing.createSubscription({
  customerId: "cus_123",
  priceId: "price_pro_monthly",
  metadata: { source: "api" },
});
```

### Parameters

| Name         | Type                  | Required | Description              |
| ------------ | --------------------- | -------- | ------------------------ |
| `customerId` | `string`              | Yes      | BillingOS customer ID    |
| `priceId`    | `string`              | Yes      | Price ID to subscribe to |
| `metadata`   | `Record<string, any>` | No       | Custom key-value pairs   |

***

## getSubscription

```typescript theme={null}
const subscription = await billing.getSubscription("sub_123");
```

***

## updateSubscription

```typescript theme={null}
const updated = await billing.updateSubscription("sub_123", {
  priceId: "price_enterprise_monthly",
  cancelAtPeriodEnd: false,
});
```

***

## cancelSubscription

```typescript theme={null}
// Cancel at end of billing period (default)
await billing.cancelSubscription("sub_123");
```

***

## reactivateSubscription

Reactivate a subscription that was cancelled but hasn't ended yet.

```typescript theme={null}
await billing.reactivateSubscription("sub_123");
```

## Subscription object

```typescript theme={null}
interface Subscription {
  id: string
  customerId: string
  stripeSubscriptionId?: string
  status: "active" | "past_due" | "canceled" | "incomplete" | "trialing"
  currentPeriodStart?: Date
  currentPeriodEnd?: Date
  cancelAtPeriodEnd: boolean
  metadata?: Record<string, any>
  createdAt: Date
  updatedAt: Date
}
```