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

# Billing & Subscriptions

Create and manage recurring subscriptions with products, prices, and billing cycles.

## Overview

Build advanced billing logic with products, recurring prices, trials, usage-based billing, and automatic invoicing. Stripe-compatible API design.

## Products

Products represent the goods or services you sell.

### Create Product

```bash theme={null}
curl -X POST https://api.atlas.co/functions/v1/products \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pro Plan",
    "description": "Full access to all features",
    "metadata": { "tier": "pro" }
  }'
```

**Parameters:**

| Parameter     | Type   | Required | Description                         |
| ------------- | ------ | -------- | ----------------------------------- |
| `name`        | string | Yes      | Product name displayed to customers |
| `description` | string | No       | Optional product description        |
| `metadata`    | object | No       | Key-value pairs for your use        |

### List Products

```bash theme={null}
curl https://api.atlas.co/functions/v1/products \
  -H "Authorization: Bearer sk_test_xxx"
```

## Prices

Prices define how much to charge for a product.

### Create Price

```bash theme={null}
curl -X POST https://api.atlas.co/functions/v1/prices \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "product": "prod_xxx",
    "currency": "usd",
    "unit_amount": 2999,
    "type": "recurring",
    "recurring": {
      "interval": "month"
    }
  }'
```

**Parameters:**

| Parameter                  | Type    | Required | Description                                 |
| -------------------------- | ------- | -------- | ------------------------------------------- |
| `product`                  | string  | Yes      | Product ID to attach price to               |
| `currency`                 | string  | Yes      | 3-letter ISO currency code (e.g. usd)       |
| `unit_amount`              | integer | No       | Amount in cents (e.g. 2999 = \$29.99)       |
| `type`                     | string  | No       | one\_time or recurring (default: one\_time) |
| `recurring.interval`       | string  | No       | day, week, month, or year                   |
| `recurring.interval_count` | integer | No       | Number of intervals (default: 1)            |
| `recurring.usage_type`     | string  | No       | licensed or metered                         |

## Subscriptions

### Create Subscription

```bash theme={null}
curl -X POST https://api.atlas.co/functions/v1/subscriptions \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": "cus_xxx",
    "items": [
      { "price": "price_xxx", "quantity": 1 }
    ],
    "trial_period_days": 14
  }'
```

**Parameters:**

| Parameter              | Type    | Required | Description                          |
| ---------------------- | ------- | -------- | ------------------------------------ |
| `customer`             | string  | Yes      | Customer ID                          |
| `items`                | array   | Yes      | Array of price objects with quantity |
| `trial_period_days`    | integer | No       | Free trial days before billing       |
| `cancel_at_period_end` | boolean | No       | Cancel at end of current period      |
| `metadata`             | object  | No       | Key-value pairs for your use         |

### Pause Subscription

```bash theme={null}
curl -X POST https://api.atlas.co/functions/v1/subscriptions/sub_xxx/pause \
  -H "Authorization: Bearer sk_test_xxx"
```

### Resume Subscription

```bash theme={null}
curl -X POST https://api.atlas.co/functions/v1/subscriptions/sub_xxx/resume \
  -H "Authorization: Bearer sk_test_xxx"
```

### Subscription Statuses

| Status     | Description                         |
| ---------- | ----------------------------------- |
| `trialing` | Customer is in free trial period    |
| `active`   | Subscription is active and billing  |
| `past_due` | Payment failed, retrying            |
| `paused`   | Subscription paused by request      |
| `canceled` | Subscription has been canceled      |
| `unpaid`   | All retries exhausted, not canceled |

## Usage Records (Metered Billing)

Report usage for metered subscription items.

```bash theme={null}
curl -X POST https://api.atlas.co/functions/v1/usage-records \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "subscription_item": "si_xxx",
    "quantity": 150,
    "action": "increment"
  }'
```

**Parameters:**

| Parameter           | Type    | Required | Description                           |
| ------------------- | ------- | -------- | ------------------------------------- |
| `subscription_item` | string  | Yes      | Subscription item ID                  |
| `quantity`          | integer | Yes      | Usage quantity to record              |
| `action`            | string  | No       | increment or set (default: increment) |
| `timestamp`         | integer | No       | Unix timestamp (default: now)         |

## Coupons

Create discount coupons for subscriptions.

```bash theme={null}
curl -X POST https://api.atlas.co/functions/v1/coupons \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "SAVE20",
    "percent_off": 20,
    "duration": "repeating",
    "duration_in_months": 3
  }'
```

**Parameters:**

| Parameter            | Type    | Required | Description                        |
| -------------------- | ------- | -------- | ---------------------------------- |
| `duration`           | string  | Yes      | once, repeating, or forever        |
| `percent_off`        | number  | No       | Percentage discount (0-100)        |
| `amount_off`         | integer | No       | Fixed amount off in cents          |
| `currency`           | string  | No       | Required if using amount\_off      |
| `duration_in_months` | integer | No       | Required if duration is repeating  |
| `max_redemptions`    | integer | No       | Max times coupon can be used       |
| `redeem_by`          | integer | No       | Unix timestamp when coupon expires |