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

# schemas

# Recurring Billing Schemas

API endpoints for managing subscription and recurring payment schedules.

## Endpoints

| Method | Endpoint                           | Description                          |
| ------ | ---------------------------------- | ------------------------------------ |
| POST   | `/v1/billing/recurring/create`     | Create recurring billing schedule    |
| POST   | `/v1/recurring/:scheduleId/pause`  | Pause recurring schedule             |
| POST   | `/v1/recurring/:scheduleId/resume` | Resume paused schedule               |
| GET    | `/v1/recurring`                    | Get recurring schedules with filters |
| GET    | `/v1/recurring/:scheduleId`        | Get specific schedule by ID          |
| DELETE | `/v1/recurring/:scheduleId`        | Cancel recurring schedule            |

## POST /v1/billing/recurring/create

Create a new recurring billing schedule for automated payments.

### Request Body

```json theme={null}
{
  "customerId": "string",
  "paymentID": "string",
  "amount": 9.99,
  "currency": "string",
  "frequency": "daily | weekly | monthly | yearly",
  "interval": 1,
  "startDate": "2024-01-01T00:00:00Z",
  "endDate": "2024-12-31T23:59:59Z",
  "maxBillings": 12,
  "description": "string",
  "metadata": {}
}
```

### Request Schema

| Field         | Type   | Required | Description                            |
| ------------- | ------ | -------- | -------------------------------------- |
| `customerId`  | string | Yes      | Customer identifier                    |
| `paymentID`   | string | Yes      | Customer payment id                    |
| `amount`      | number | Yes      | Billing amount                         |
| `currency`    | string | Yes      | Currency code                          |
| `frequency`   | string | Yes      | Billing frequency                      |
| `interval`    | number | No       | Interval between billings (default: 1) |
| `startDate`   | string | Yes      | Schedule start date                    |
| `endDate`     | string | No       | Schedule end date                      |
| `maxBillings` | number | No       | Maximum number of billings             |
| `description` | string | No       | Schedule description                   |
| `metadata`    | object | No       | Additional metadata                    |

### Response Schema

```json theme={null}
{
  "statusCode": 201,
  "success": true,
  "message": "Recurring schedule created successfully",
  "data": {
    "scheduleId": "string",
    "customerId": "string",
    "amount": 9.99,
    "frequency": "monthly",
    "status": "active",
    "nextBillingDate": "2024-02-01T00:00:00Z"
  }
}
```

## POST /v1/recurring/:scheduleId/pause

Pause an active recurring billing schedule.

### Request Body

```json theme={null}
{
  "reason": "string"
}
```

### Response Schema

```json theme={null}
{
  "statusCode": 200,
  "success": true,
  "message": "Recurring schedule paused successfully",
  "data": {
    "scheduleId": "string",
    "status": "paused",
    "pausedAt": "2024-01-01T00:00:00Z"
  }
}
```

## POST /v1/recurring/:scheduleId/resume

Resume a paused recurring billing schedule.

### Request Body

```json theme={null}
{
  "reason": "string"
}
```

### Response Schema

```json theme={null}
{
  "statusCode": 200,
  "success": true,
  "message": "Recurring schedule resumed successfully",
  "data": {
    "scheduleId": "string",
    "status": "active",
    "resumedAt": "2024-01-01T00:00:00Z",
    "nextBillingDate": "2024-02-01T00:00:00Z"
  }
}
```

## GET /v1/recurring

Get multiple recurring billing schedules with optional filters.

### Query Parameters

| Parameter    | Type   | Required | Description                                  |
| ------------ | ------ | -------- | -------------------------------------------- |
| `customerId` | string | No       | Filter by customer ID                        |
| `status`     | string | No       | Filter by status (active, paused, cancelled) |
| `limit`      | number | No       | Number of results to return                  |
| `skip`       | number | No       | Number of results to skip                    |

### Response Schema

```json theme={null}
{
  "statusCode": 200,
  "success": true,
  "data": {
    "schedules": [
      {
        "scheduleId": "string",
        "customerId": "string",
        "amount": 9.99,
        "currency": "string",
        "frequency": "monthly",
        "status": "active",
        "nextBillingDate": "2024-02-01T00:00:00Z",
        "totalBillings": 5,
        "createdAt": "2024-01-01T00:00:00Z"
      }
    ],
    "total": 1
  }
}
```

## Recurring Schedule Schema

| Field             | Type   | Description                |
| ----------------- | ------ | -------------------------- |
| `scheduleId`      | string | Unique schedule identifier |
| `customerId`      | string | Customer identifier        |
| `paymentID`       | string | Payment ID for billing     |
| `amount`          | number | Billing amount             |
| `currency`        | string | Currency code              |
| `frequency`       | string | Billing frequency          |
| `interval`        | number | Interval between billings  |
| `status`          | string | Schedule status            |
| `startDate`       | string | Schedule start date        |
| `endDate`         | string | Schedule end date          |
| `nextBillingDate` | string | Next billing date          |
| `totalBillings`   | number | Total billings processed   |
| `maxBillings`     | number | Maximum billings allowed   |
| `failedAttempts`  | number | Failed billing attempts    |
| `description`     | string | Schedule description       |
| `createdAt`       | string | Creation timestamp         |

## Status Types

| Status       | Description                         |
| ------------ | ----------------------------------- |
| `active`     | Schedule is active and processing   |
| `paused`     | Schedule is temporarily paused      |
| `cancelled`  | Schedule has been cancelled         |
| `completed`  | Schedule has completed all billings |
| `processing` | Schedule is currently processing    |

## Error Responses

### 400 Bad Request

```json theme={null}
{
  "statusCode": 400,
  "success": false,
  "message": "Customer must have approve_recurring permission"
}
```

### 404 Not Found

```json theme={null}
{
  "statusCode": 404,
  "success": false,
  "message": "Recurring schedule not found"
}
```