Custom Integration

Build a custom integration with Yeld using our REST API. This guide covers the basics for integrating with any technology stack.

**API Base URL:**
```
https://api.yeld.app/v1
```

**Authentication:**
All requests require an API key in the Authorization header:
```
Authorization: Bearer YOUR_API_KEY
```

**POST /checkout-links/:bizId**

```typescript
const response = await fetch(
  "https://api.yeld.app/v1/checkout-links/biz_abc123",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${apiKey}`,
    },
    body: JSON.stringify({
      planName: "Premium Plan",
      plan: "premium",
      description: "Full access subscription",
      price: "50.00",
      billing: "recurring",
      initialFee: "10.00",
      trialDays: 7,
      stock: 100,
    }),
  }
);

const data = await response.json();
console.log(data); // { ok: true }
```

**GET /checkout-links/:bizId**

```typescript
const response = await fetch(
  "https://api.yeld.app/v1/checkout-links/biz_abc123",
  {
    headers: {
      Authorization: `Bearer ${apiKey}`,
    },
  }
);

const links = await response.json();
console.log(links);
// [
//   {
//     id: "uuid",
//     planId: "plan_abc123",
//     planName: "Premium Plan",
//     price: "50.00",
//     billing: "recurring",
//     // ...
//   }
// ]
```

**DELETE /checkout-links/:bizId/:planId**

```typescript
const response = await fetch(
  "https://api.yeld.app/v1/checkout-links/biz_abc123/plan_xyz789",
  {
    method: "DELETE",
    headers: {
      Authorization: `Bearer ${apiKey}`,
    },
  }
);

const data = await response.json();
console.log(data); // { ok: true }
```

**Error Response Format:**
```json
{
  "ok": false,
  "error": "Error message here"
}
```

**Common Errors:**
- 400: Bad Request - Invalid input
- 401: Unauthorized - Invalid API key
- 403: Forbidden - Insufficient permissions
- 404: Not Found - Resource doesn't exist
- 429: Too Many Requests - Rate limited

**Handling Errors:**
```typescript
async function apiCall(endpoint: string, options: RequestInit) {
  const response = await fetch(endpoint, {
    ...options,
    headers: {
      ...options.headers,
      Authorization: `Bearer ${apiKey}`,
    },
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error || `HTTP ${response.status}`);
  }

  return response.json();
}
```

**Full Integration Example:**

```typescript
class YeldClient {
  private baseUrl = "https://api.yeld.app/v1";
  private apiKey: string;

  constructor(apiKey: string) {
    this.apiKey = apiKey;
  }

  private async request<T>(
    endpoint: string,
    options: RequestInit = {}
  ): Promise<T> {
    const response = await fetch(
      `${this.baseUrl}${endpoint}`,
      {
        ...options,
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${this.apiKey}`,
          ...options.headers,
        },
      }
    );

    if (!response.ok) {
      const error = await response.json();
      throw new Error(error.error || `HTTP ${response.status}`);
    }

    return response.json();
  }

  async createCheckoutLink(
    bizId: string,
    data: {
      planName: string;
      plan: string;
      description: string;
      price: string;
      billing: "one-time" | "recurring";
    }
  ) {
    return this.request(`/checkout-links/${bizId}`, {
      method: "POST",
      body: JSON.stringify(data),
    });
  }

  async getCheckoutLinks(bizId: string) {
    return this.request(`/checkout-links/${bizId}`);
  }

  async deleteCheckoutLink(bizId: string, planId: string) {
    return this.request(`/checkout-links/${bizId}/${planId}`, {
      method: "DELETE",
    });
  }
}

// Usage
const yeld = new YeldClient(process.env.YELD_API_KEY!);

const link = await yeld.createCheckoutLink("biz_abc123", {
  planName: "Premium Plan",
  plan: "premium",
  description: "Full access",
  price: "50.00",
  billing: "recurring",
});
```