# Polar.sh Integration via LowCodeAPI

## Overview

Polar.sh is a modern payment and subscription platform designed for creators and developers. The Polar.sh API provides comprehensive functionality for:

- **Products & Pricing** - Create and manage products with flexible pricing options
- **Checkout** - Generate checkout sessions for one-time and subscription purchases
- **Orders & Subscriptions** - Manage customer orders and active subscriptions
- **Benefits** - Define and manage product benefits and entitlements
- **Customers** - Handle customer accounts and information
- **Webhooks** - Configure webhook notifications for events
- **License Keys** - Generate and validate software license keys

## Base Endpoint

```
https://api.lowcodeapi.com/polarsh/
```

## Authentication

LowCodeAPI handles authentication automatically using Bearer token authentication. You only need to:

1. **Sign up** at [Polar.sh](https://polar.sh) to get your Organization Access Token (OAT)
2. **Connect your account** in the LowCodeAPI dashboard
3. **Use your `api_token`** in all requests

The `api_token` is your LowCodeAPI authentication token. LowCodeAPI will automatically:
- Fetch your Polar.sh OAT
- Apply it to each request as a Bearer token

**Auth Type**: Bearer Token (Organization Access Token)

## API Categories

- **Payment Processing** - Products, subscriptions, and payment management

## Common Endpoints

### Category: Products

#### List Products

**Method**: `GET` | **LowCodeAPI Path**: `/v1/products`

**Full URL**:
```
https://api.lowcodeapi.com/polarsh/v1/products?api_token={api_token}
```

**Description**: List all products in your organization.

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `page` | integer | No | Page number, starting from 1 (default: 1) |
| `limit` | integer | No | Number of items per page, max 100 (default: 10) |

**Example Request**:
```bash
curl -X GET "https://api.lowcodeapi.com/polarsh/v1/products?api_token=YOUR_API_TOKEN&page=1&limit=20"
```

**Official Documentation**: [List Products](https://polar.sh/docs/api-reference/products/list)

---

#### Create Product

**Method**: `POST` | **LowCodeAPI Path**: `/v1/products`

**Full URL**:
```
https://api.lowcodeapi.com/polarsh/v1/products?api_token={api_token}
```

**Description**: Create a new product in your organization.

**Request Body**:
```json
{
  "name": "Pro Plan",
  "description": "Professional subscription plan",
  "metadata": {
    "tier": "professional",
    "features": ["feature1", "feature2"]
  }
}
```

**Request Body Fields**:

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | Yes | Product name |
| `description` | string | No | Product description |
| `metadata` | object | No | Additional metadata for the product |

**Example Request**:
```bash
curl -X POST "https://api.lowcodeapi.com/polarsh/v1/products?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Premium Subscription",
    "description": "Access to all premium features"
  }'
```

**Official Documentation**: [Create Product](https://polar.sh/docs/api-reference/products/create)

---

#### Get Product

**Method**: `GET` | **LowCodeAPI Path**: `/v1/products/product_id`

**Full URL**:
```
https://api.lowcodeapi.com/polarsh/v1/products/product_id?product_id={product_id}&api_token={api_token}
```

**Description**: Get a specific product by ID.

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `product_id` | string | Yes | Product ID |

**Example Request**:
```bash
curl -X GET "https://api.lowcodeapi.com/polarsh/v1/products/product_id?product_id=prod_123&api_token=YOUR_API_TOKEN"
```

**Official Documentation**: [Get Product](https://polar.sh/docs/api-reference/products/get)

---

#### Update Product

**Method**: `PATCH` | **LowCodeAPI Path**: `/v1/products/product_id`

**Full URL**:
```
https://api.lowcodeapi.com/polarsh/v1/products/product_id?product_id={product_id}&api_token={api_token}
```

**Description**: Update a product.

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `product_id` | string | Yes | Product ID |

**Request Body Fields**:

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | No | Product name |
| `description` | string | No | Product description |
| `metadata` | object | No | Additional metadata for the product |

**Example Request**:
```bash
curl -X PATCH "https://api.lowcodeapi.com/polarsh/v1/products/product_id?product_id=prod_123&api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Product Name",
    "description": "Updated description"
  }'
```

**Official Documentation**: [Update Product](https://polar.sh/docs/api-reference/products/update)

---

#### Delete Product

**Method**: `DELETE` | **LowCodeAPI Path**: `/v1/products/product_id`

**Full URL**:
```
https://api.lowcodeapi.com/polarsh/v1/products/product_id?product_id={product_id}&api_token={api_token}
```

**Description**: Delete a product.

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `product_id` | string | Yes | Product ID |

**Example Request**:
```bash
curl -X DELETE "https://api.lowcodeapi.com/polarsh/v1/products/product_id?product_id=prod_123&api_token=YOUR_API_TOKEN"
```

**Official Documentation**: [Delete Product](https://polar.sh/docs/api-reference/products/delete)

---

### Category: Prices

#### List Prices

**Method**: `GET` | **LowCodeAPI Path**: `/v1/prices`

**Full URL**:
```
https://api.lowcodeapi.com/polarsh/v1/prices?api_token={api_token}
```

**Description**: List all prices.

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `page` | integer | No | Page number, starting from 1 (default: 1) |
| `limit` | integer | No | Items per page, max 100 (default: 10) |
| `product_id` | string | No | Filter prices by product ID |

**Example Request**:
```bash
curl -X GET "https://api.lowcodeapi.com/polarsh/v1/prices?api_token=YOUR_API_TOKEN&product_id=prod_123"
```

**Official Documentation**: [List Prices](https://polar.sh/docs/api-reference/prices/list)

---

#### Create Price

**Method**: `POST` | **LowCodeAPI Path**: `/v1/prices`

**Full URL**:
```
https://api.lowcodeapi.com/polarsh/v1/prices?api_token={api_token}
```

**Description**: Create a new price for a product.

**Request Body**:
```json
{
  "product_id": "prod_123",
  "amount": 999,
  "currency": "USD",
  "recurring": {
    "interval": "month"
  }
}
```

**Request Body Fields**:

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `product_id` | string | Yes | Product ID |
| `amount` | integer | Yes | Price amount in cents |
| `currency` | string | Yes | Currency code (e.g., USD, EUR) |
| `recurring` | object | No | Recurring pricing configuration |
| `metadata` | object | No | Additional metadata for the price |

**Example Request**:
```bash
curl -X POST "https://api.lowcodeapi.com/polarsh/v1/prices?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "prod_123",
    "amount": 1999,
    "currency": "USD",
    "recurring": {"interval": "month"}
  }'
```

**Official Documentation**: [Create Price](https://polar.sh/docs/api-reference/prices/create)

---

### Category: Checkout

#### Create Checkout

**Method**: `POST` | **LowCodeAPI Path**: `/v1/checkouts`

**Full URL**:
```
https://api.lowcodeapi.com/polarsh/v1/checkouts?api_token={api_token}
```

**Description**: Create a new checkout session.

**Request Body**:
```json
{
  "product_id": "prod_123",
  "price_id": "price_123",
  "success_url": "https://example.com/success",
  "customer_email": "[email protected]"
}
```

**Request Body Fields**:

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `product_id` | string | Yes | Product ID |
| `price_id` | string | Yes | Price ID |
| `success_url` | string | No | URL to redirect after successful checkout |
| `customer_email` | string | No | Customer email address |
| `external_customer_id` | string | No | External customer ID |
| `metadata` | object | No | Additional metadata for the checkout |

**Example Request**:
```bash
curl -X POST "https://api.lowcodeapi.com/polarsh/v1/checkouts?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "prod_123",
    "price_id": "price_123",
    "success_url": "https://example.com/thank-you"
  }'
```

**Official Documentation**: [Create Checkout](https://polar.sh/docs/api-reference/checkout/create)

---

### Category: Subscriptions

#### List Subscriptions

**Method**: `GET` | **LowCodeAPI Path**: `/v1/subscriptions`

**Full URL**:
```
https://api.lowcodeapi.com/polarsh/v1/subscriptions?api_token={api_token}
```

**Description**: List all subscriptions.

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `page` | integer | No | Page number, starting from 1 (default: 1) |
| `limit` | integer | No | Items per page, max 100 (default: 10) |
| `customer_id` | string | No | Filter subscriptions by customer ID |

**Example Request**:
```bash
curl -X GET "https://api.lowcodeapi.com/polarsh/v1/subscriptions?api_token=YOUR_API_TOKEN&customer_id=cust_123"
```

**Official Documentation**: [List Subscriptions](https://polar.sh/docs/api-reference/subscriptions/list)

---

#### Cancel Subscription

**Method**: `POST` | **LowCodeAPI Path**: `/v1/subscriptions/subscription_id/cancel`

**Full URL**:
```
https://api.lowcodeapi.com/polarsh/v1/subscriptions/subscription_id/cancel?subscription_id={subscription_id}&api_token={api_token}
```

**Description**: Cancel a subscription.

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `subscription_id` | string | Yes | Subscription ID |

**Example Request**:
```bash
curl -X POST "https://api.lowcodeapi.com/polarsh/v1/subscriptions/subscription_id/cancel?subscription_id=sub_123&api_token=YOUR_API_TOKEN"
```

**Official Documentation**: [Cancel Subscription](https://polar.sh/docs/api-reference/subscriptions/cancel)

---

### Category: Benefits

#### Create Benefit

**Method**: `POST` | **LowCodeAPI Path**: `/v1/benefits`

**Full URL**:
```
https://api.lowcodeapi.com/polarsh/v1/benefits?api_token={api_token}
```

**Description**: Create a new benefit for a product.

**Request Body**:
```json
{
  "product_id": "prod_123",
  "description": "Access to premium features",
  "type": "github_repository",
  "properties": {
    "repository_id": "123456"
  }
}
```

**Request Body Fields**:

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `product_id` | string | Yes | Product ID |
| `description` | string | Yes | Benefit description |
| `type` | string | Yes | Benefit type |
| `properties` | object | No | Benefit properties |
| `metadata` | object | No | Additional metadata for the benefit |

**Example Request**:
```bash
curl -X POST "https://api.lowcodeapi.com/polarsh/v1/benefits?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "prod_123",
    "description": "Access to private GitHub repository",
    "type": "github_repository"
  }'
```

**Official Documentation**: [Create Benefit](https://polar.sh/docs/api-reference/benefits/create)

---

### Category: Customers

#### Create Customer

**Method**: `POST` | **LowCodeAPI Path**: `/v1/customers`

**Full URL**:
```
https://api.lowcodeapi.com/polarsh/v1/customers?api_token={api_token}
```

**Description**: Create a new customer.

**Request Body**:
```json
{
  "email": "[email protected]",
  "name": "John Doe",
  "metadata": {
    "source": "website"
  }
}
```

**Request Body Fields**:

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `email` | string | Yes | Customer email address |
| `name` | string | No | Customer name |
| `metadata` | object | No | Additional metadata for the customer |

**Example Request**:
```bash
curl -X POST "https://api.lowcodeapi.com/polarsh/v1/customers?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "name": "John Doe"
  }'
```

**Official Documentation**: [Create Customer](https://polar.sh/docs/api-reference/customers/create)

---

### Category: Webhooks

#### Create Webhook

**Method**: `POST` | **LowCodeAPI Path**: `/v1/webhooks`

**Full URL**:
```
https://api.lowcodeapi.com/polarsh/v1/webhooks?api_token={api_token}
```

**Description**: Create a new webhook subscription.

**Request Body**:
```json
{
  "url": "https://example.com/webhook",
  "events": ["order.created", "subscription.created"]
}
```

**Request Body Fields**:

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `url` | string | Yes | Webhook URL |
| `events` | array | Yes | List of events to subscribe to |
| `secret` | string | No | Webhook secret for signature verification |
| `metadata` | object | No | Additional metadata for the webhook |

**Example Request**:
```bash
curl -X POST "https://api.lowcodeapi.com/polarsh/v1/webhooks?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/polar-webhook",
    "events": ["order.created", "subscription.updated"]
  }'
```

**Official Documentation**: [Create Webhook](https://polar.sh/docs/api-reference/webhooks/create)

---

### Category: License Keys

#### Validate License Key

**Method**: `POST` | **LowCodeAPI Path**: `/v1/customer-portal/license-keys/validate`

**Full URL**:
```
https://api.lowcodeapi.com/polarsh/v1/customer-portal/license-keys/validate?api_token={api_token}
```

**Description**: Validate a license key (unauthenticated endpoint).

**Request Body**:
```json
{
  "license_key": "POLAR-XXXX-XXXX-XXXX"
}
```

**Request Body Fields**:

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `license_key` | string | Yes | License key to validate |

**Example Request**:
```bash
curl -X POST "https://api.lowcodeapi.com/polarsh/v1/customer-portal/license-keys/validate?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"license_key": "POLAR-ABCD-1234-EFGH"}'
```

**Official Documentation**: [Validate License](https://polar.sh/docs/api-reference/customer-portal/license-keys/validate)

---

## Usage Examples

### Example 1: Create a Product with Subscription Pricing

Set up a subscription product:

```bash
# Step 1: Create a product
# No ID needed - creates new product
curl -X POST "https://api.lowcodeapi.com/polarsh/v1/products?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pro Subscription",
    "description": "Monthly subscription to pro features"
  }'

# Step 2: Create a recurring price for the product
# Replace PRODUCT_ID with the actual product ID from Step 1
curl -X POST "https://api.lowcodeapi.com/polarsh/v1/prices?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "PRODUCT_ID",
    "amount": 1999,
    "currency": "USD",
    "recurring": {"interval": "month"}
  }'

# Step 3: Create a checkout session
# Replace PRICE_ID with the actual price ID from Step 2
curl -X POST "https://api.lowcodeapi.com/polarsh/v1/checkouts?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "PRODUCT_ID",
    "price_id": "PRICE_ID",
    "success_url": "https://example.com/success"
  }'
```

### Example 2: Manage Subscriptions

Handle customer subscriptions:

```bash
# Step 1: List subscriptions for a customer
# Replace CUSTOMER_ID with actual customer ID
curl -X GET "https://api.lowcodeapi.com/polarsh/v1/subscriptions?api_token=YOUR_API_TOKEN&customer_id=CUSTOMER_ID"

# Step 2: Cancel a subscription
# Replace SUBSCRIPTION_ID with actual subscription ID
curl -X POST "https://api.lowcodeapi.com/polarsh/v1/subscriptions/subscription_id/cancel?subscription_id=SUBSCRIPTION_ID&api_token=YOUR_API_TOKEN"
```

### Example 3: Set Up Benefits and Webhooks

Configure product benefits and notifications:

```bash
# Step 1: Create a benefit for a product
# Replace PRODUCT_ID with actual product ID
curl -X POST "https://api.lowcodeapi.com/polarsh/v1/benefits?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "PRODUCT_ID",
    "description": "Access to premium content",
    "type": "custom"
  }'

# Step 2: Create webhook for event notifications
# No ID needed - creates new webhook
curl -X POST "https://api.lowcodeapi.com/polarsh/v1/webhooks?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhook",
    "events": ["order.created", "subscription.updated"]
  }'
```

## Complete Endpoint Reference

For a complete list of all 60 endpoints and their parameters, refer to:

- **OpenAPI Definition**: https://backend.lowcodeapi.com/polarsh/definition
- **Official Polar.sh Documentation**: https://polar.sh/docs/api-reference/introduction

## Rate Limits

- **Rate Limit**: 300 requests per minute
- **License Key Endpoints**: 3 requests per second (unauthenticated)

## Error Handling

All responses are wrapped in a `data` key:
```json
{
  "data": {
    // Actual response from Polar.sh
  }
}
```