Chargebee

通过受管 OAuth 认证访问 Chargebee API，用于管理订阅、客户、发票及计费工作流。

快速入门

# 列出客户
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/chargebee/api/v2/customers?limit=10')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

基础 URL

https://api.maton.ai/chargebee/{endpoint-path}

网关将请求代理至 {subdomain}.chargebee.com（自动替换为您的连接配置），并注入认证信息。仅支持下方「API 参考」章节中明确记录的端点 —— 请始终使用该章节中列出的具体端点路径，而非自行构造任意路径。

认证

所有请求均需在 Authorization 请求头中提供 Maton API 密钥：

Authorization: Bearer $MATON_API_KEY

环境变量：请将您的 API 密钥设置为 MATON_API_KEY：

export MATON_API_KEY="YOUR_API_KEY"

获取您的 API 密钥

1. 在 maton.ai 登录或注册账户
2. 访问 maton.ai/settings
3. 复制您的 API 密钥

连接管理

您可在 https://api.maton.ai 管理您的 Chargebee 连接。

列出连接

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections?app=chargebee&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

创建连接

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'chargebee'}).encode()
req = urllib.request.Request('https://api.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

获取连接

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections/{connection_id}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

响应示例：

{
  "connection": {
    "connection_id": "{connection_id}",
    "status": "ACTIVE",
    "creation_time": "2025-12-08T07:20:53.488460Z",
    "last_updated_time": "2026-01-31T20:03:32.593153Z",
    "url": "https://connect.maton.ai/?session_token=...",
    "app": "chargebee",
    "metadata": {}
  }
}

在浏览器中打开返回的 url，完成 OAuth 授权流程。

删除连接

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections/{connection_id}', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

指定连接

若您拥有多个 Chargebee 连接，请使用 Maton-Connection 请求头明确指定目标连接：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/chargebee/api/v2/customers')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', '{connection_id}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

请始终包含 Maton-Connection 请求头，以确保请求路由至预期的 Chargebee 账户，尤其在执行任何写入操作前。若您拥有多个连接却未指定该请求头，网关将使用默认连接，这可能并非您期望的目标账户。

安全与权限

• 访问范围受限于已连接账户凭据所允许的 Chargebee 资源。仅在确有 Chargebee 计费管理需求时安装。请遵循最小权限原则，并及时撤销不再使用的连接。
• 默认执行只读操作。 所有变更操作前，请先通过列表或获取资源确认目标标识符。
• 所有写入操作均需用户明确授权，并附带具体操作细节。 在执行任何 POST、PUT 或取消/删除调用前：
  1. 获取并展示目标资源（如客户名称/ID、订阅 ID、发票编号），供用户核对；
  2. 清晰说明预期影响（例如：“此操作将取消客户 ‘Acme Corp’ 的订阅 ‘sub_123’，计费将在当前计费周期结束时停止”）；
  3. 等待用户明确确认后方可继续执行。
• 计费相关操作具有高影响性。 任何涉及订阅、发票或客户计费记录的操作，均须附带财务影响摘要，并强制要求用户确认。

API 参考

客户

列出客户

GET /chargebee/api/v2/customers?limit=10

获取客户

GET /chargebee/api/v2/customers/{customerId}

创建客户

POST /chargebee/api/v2/customers
Content-Type: application/x-www-form-urlencoded

first_name=John&last_name=Doe&email=john@example.com

更新客户

POST /chargebee/api/v2/customers/{customerId}
Content-Type: application/x-www-form-urlencoded

first_name=Jane

订阅

列出订阅

GET /chargebee/api/v2/subscriptions?limit=10

获取订阅

GET /chargebee/api/v2/subscriptions/{subscriptionId}

创建订阅

POST /chargebee/api/v2/subscriptions
Content-Type: application/x-www-form-urlencoded

plan_id=basic-plan&customer[email]=john@example.com&customer[first_name]=John

取消订阅

POST /chargebee/api/v2/subscriptions/{subscriptionId}/cancel
Content-Type: application/x-www-form-urlencoded

end_of_term=true

商品价格（产品目录 2.0）

列出商品价格

GET /chargebee/api/v2/item_prices?limit=10

商品

列出商品

GET /chargebee/api/v2/items?limit=10

发票

列出发票

GET /chargebee/api/v2/invoices?limit=10

下载发票 PDF

POST /chargebee/api/v2/invoices/{invoiceId}/pdf

托管页面

新订阅结账页

POST /chargebee/api/v2/hosted_pages/checkout_new_for_items
Content-Type: application/x-www-form-urlencoded

subscription[plan_id]=basic-plan&customer[email]=john@example.com

门户会话

创建门户会话

POST /chargebee/api/v2/portal_sessions
Content-Type: application/x-www-form-urlencoded

customer[id]=cust_123

筛选

GET /chargebee/api/v2/subscriptions?status[is]=active
GET /chargebee/api/v2/customers?email[is]=john@example.com
GET /chargebee/api/v2/invoices?date[after]=1704067200

代码示例

JavaScript

const response = await fetch(
  'https://api.maton.ai/chargebee/api/v2/customers?limit=10',
  {
    headers: {
      'Authorization': `Bearer ${process.env.MATON_API_KEY}`
    }
  }
);

Python

import os
import requests

response = requests.get(
    'https://api.maton.ai/chargebee/api/v2/customers',
    headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'},
    params={'limit': 10}
)

注意事项

• POST 请求使用 form-urlencoded 格式数据
• 嵌套对象采用方括号表示法：如 customer[email]
• 时间戳为 Unix 时间戳格式
• 列表响应中包含 next_offset 字段用于分页
• 产品目录 2.0：请使用 item_prices 和 items
• 重要提示：使用 curl 命令时，若 URL 中含方括号（如 fields[]、sort[]、records[]），请添加 -g 参数禁用 glob 解析
• 重要提示：当将 curl 输出管道传递给 jq 或其他命令时，在部分 shell 环境中环境变量（如 $MATON_API_KEY）可能无法正确展开，导致出现“Invalid API key”错误

错误处理

问题排查：API 密钥异常

1. 确认已设置 MATON_API_KEY 环境变量：

echo $MATON_API_KEY

2. 通过列出连接验证 API 密钥有效性：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

问题排查：应用名称无效

1. 确保您的 URL 路径以 chargebee 开头。例如：

• 正确： https://api.maton.ai/chargebee/api/v2/customers
• 错误： https://api.maton.ai/api/v2/customers

资源

• Chargebee API 概览
• 客户
• 订阅
• 发票
• 托管页面
• Maton 社区
• Maton 支持