Subscriptions

Subscriptions allow you to charge customers on a recurring basis. Yeld handles the billing cycle and payment collection automatically.

**Subscription Flow:**
1. Customer signs up for a subscription plan
2. They pay the initial amount (if applicable)
3. Yeld charges the customer at the specified interval
4. You receive payments automatically
5. You can manage subscriptions from your dashboard

Create a subscription plan with recurring billing:

```typescript
await createCheckoutLink("biz_your_business_id", {
  planName: "Premium Monthly",
  plan: "premium-monthly",
  description: "Monthly premium subscription with full access",
  price: "29.00",
  billing: "recurring",
  initialFee: "10.00",    // Optional: charge upfront
  trial: "7",             // Optional: 7-day free trial
  stock: "100",           // Optional: limit subscriptions
});
```

**Plan Properties:**
- `planName`: Display name shown to customers
- `plan`: Internal identifier for the plan
- `price`: Monthly/yearly charge amount in USD
- `billing`: Set to "recurring" for subscriptions
- `initialFee`: One-time upfront charge (optional)
- `trial`: Free trial period in days (optional)
- `stock`: Maximum number of subscriptions (optional)

**Managing Active Subscriptions:**

```typescript
// Get all checkout links (includes subscriptions)
const links = await getCheckoutLinks("biz_your_business_id");

// Filter for subscriptions
const subscriptions = links.filter(link => link.billing === "recurring");

// Get a specific subscription
const subscription = await getCheckoutLinkByPlanId("plan_abc123");

console.log(subscription);
// {
//   planId: "plan_abc123",
//   planName: "Premium Monthly",
//   price: "29.00",
//   billing: "recurring",
//   trialDays: 7,
//   createdAt: Date,
//   // ...
// }
```

**Canceling a Subscription:**
Delete the checkout link to prevent new subscriptions. Existing subscriptions continue until the end of their billing cycle.

Receive notifications about subscription events:

```typescript
// Webhook handler for subscription events
export async function POST(request: Request) {
  const payload = await request.text();
  const event = JSON.parse(payload);

  switch (event.type) {
    case "subscription.created":
      // New subscription started
      await sendWelcomeEmail(event.data.customerId);
      break;
      
    case "subscription.renewed":
      // Subscription payment successful
      await updateCustomerAccess(event.data.customerId);
      break;
      
    case "subscription.cancelled":
      // Subscription cancelled
      await sendCancellationEmail(event.data.customerId);
      break;
      
    case "payment.failed":
      // Recurring payment failed
      await notifyCustomer(event.data.customerId);
      break;
  }

  return Response.json({ received: true });
}
```