Standard Production RESTful API Markdown Documentation Template

# API Documentation: Payment & Subscription Service

**Base URL:** `https://api.example.com/v1`  
**Current Version:** `1.4.0`  
**Protocol:** HTTPS only  

---

## 1. Authentication
All API requests require a valid Bearer Token in the HTTP Authorization header:

```http
Authorization: Bearer sec_live_9f830a7d2b5e4c19
```

---

## 2. Standard Response Wrapper
All successful API responses return JSON data encapsulated in a standard envelope:

```json
{
  "success": true,
  "data": { ... },
  "meta": {
    "requestId": "req_8893a7f",
    "timestamp": "2026-11-06T12:00:00Z"
  }
}
```

---

## 3. Endpoints

### Create Subscription
`POST /subscriptions`

Creates an active billing recurring subscription for an existing customer account.

#### Request Headers
| Header | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `Authorization` | String | Yes | Bearer token authentication |
| `Content-Type` | String | Yes | `application/json` |
| `Idempotency-Key` | String | No | Unique UUID to prevent double charges |

#### Request Body
```json
{
  "customerId": "cus_99214b7e",
  "planId": "plan_pro_annual",
  "currency": "USD",
  "paymentMethodId": "pm_card_visa_4242"
}
```

#### Status Responses
| HTTP Code | Reason | Description |
| :--- | :--- | :--- |
| `201 Created` | Subscription Active | New subscription created and first billing invoice generated |
| `400 Bad Request` | Validation Error | Missing required fields or invalid currency code |
| `401 Unauthorized`| Invalid Token | Bearer authentication token is expired or revoked |
| `409 Conflict` | Duplicate Charge | Idempotency key already processed in previous request |

---

## 4. Error Code Reference
When an error occurs, the API returns a structured error object with human-readable hints:

```json
{
  "success": false,
  "error": {
    "code": "CARD_DECLINED",
    "message": "The customer payment card has insufficient funds.",
    "param": "paymentMethodId"
  }
}
```