Gumroad

2026-03-28 新闻来源：网淘吧围观:16

电脑广告

手机广告

Gumroad

通过托管的OAuth认证访问Gumroad API。管理产品、查看销售、验证许可证，并为您的数字店面设置网络钩子。

快速入门

# Get current user info
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/gumroad/v2/user')
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://gateway.maton.ai/gumroad/v2/{resource}

网关将请求代理至api.gumroad.com/v2并自动注入您的OAuth令牌。

认证

所有请求都需要在Authorization头部中包含Maton API密钥：

Authorization: Bearer $MATON_API_KEY

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

export MATON_API_KEY="YOUR_API_KEY"

获取您的API密钥

登录或创建账户于maton.ai
前往maton.ai/settings
复制您的API密钥

连接管理

在以下地址管理您的Gumroad OAuth连接：https://ctrl.maton.ai.

列出连接

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=gumroad&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': 'gumroad'}).encode()
req = urllib.request.Request('https://ctrl.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://ctrl.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": "e1a4444f-2bb8-4e09-9265-3afe71b74b1f",
    "status": "ACTIVE",
    "creation_time": "2026-02-08T06:22:48.654579Z",
    "last_updated_time": "2026-02-08T06:23:07.420381Z",
    "url": "https://connect.maton.ai/?session_token=...",
    "app": "gumroad",
    "metadata": {}
  }
}

在浏览器中打开返回的网址以完成 OAuth 授权。

删除连接

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.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

指定连接

如果您有多个 Gumroad 连接，请通过Maton-Connection标头指定要使用的连接：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/gumroad/v2/products')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', 'e1a4444f-2bb8-4e09-9265-3afe71b74b1f')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

如果省略，网关将使用默认的（最早创建的）活动连接。

API 参考

用户信息

获取当前用户

GET /gumroad/v2/user

响应：

{
  "success": true,
  "user": {
    "name": "Chris",
    "currency_type": "usd",
    "bio": null,
    "twitter_handle": null,
    "id": "1690942847664",
    "user_id": "QmTtTnViFSoocHAexgLuJw==",
    "url": "https://chriswave1246.gumroad.com",
    "profile_url": "https://public-files.gumroad.com/...",
    "email": "chris@example.com",
    "display_name": "Chris"
  }
}

产品操作

列出产品

GET /gumroad/v2/products

响应：

{
  "success": true,
  "products": [
    {
      "id": "ABC123",
      "name": "My Product",
      "price": 500,
      "currency": "usd",
      "short_url": "https://gumroad.com/l/abc",
      "sales_count": 10,
      "sales_usd_cents": 5000
    }
  ]
}

获取产品

GET /gumroad/v2/products/{product_id}

更新产品

PUT /gumroad/v2/products/{product_id}
Content-Type: application/x-www-form-urlencoded

name=Updated%20Name&price=1000

启用/禁用产品

PUT /gumroad/v2/products/{product_id}/disable
Content-Type: application/x-www-form-urlencoded

disabled=true

删除产品

DELETE /gumroad/v2/products/{product_id}

注意：不支持通过API创建新产品。产品必须通过Gumroad网站创建。

优惠码操作

列出优惠码

GET /gumroad/v2/products/{product_id}/offer_codes

获取优惠码

GET /gumroad/v2/products/{product_id}/offer_codes/{offer_code_id}

创建优惠码

POST /gumroad/v2/products/{product_id}/offer_codes
Content-Type: application/x-www-form-urlencoded

name=SUMMER20&amount_off=20

参数：

名称- 客户输入的代码（必需）
减免金额- 减免的金额（美分）或百分比（必需）
优惠类型- "美分" 或 "百分比"（默认："美分"）
最大购买次数- 最大使用次数（可选）

更新优惠码

PUT /gumroad/v2/products/{product_id}/offer_codes/{offer_code_id}
Content-Type: application/x-www-form-urlencoded

max_purchase_count=100

删除优惠码

DELETE /gumroad/v2/products/{product_id}/offer_codes/{offer_code_id}

销售操作

列出销售记录

GET /gumroad/v2/sales

查询参数：

之后- 仅此日期之后（YYYY-MM-DD格式）的销售记录
之前- 仅限此日期之前的销售记录（格式：YYYY-MM-DD）
页码- 用于分页的页码

使用筛选器的示例：

GET /gumroad/v2/sales?after=2026-01-01&before=2026-12-31

响应：

{
  "success": true,
  "sales": [
    {
      "id": "sale_abc123",
      "email": "customer@example.com",
      "seller_id": "seller123",
      "product_id": "prod123",
      "product_name": "My Product",
      "price": 500,
      "currency_symbol": "$",
      "created_at": "2026-01-15T10:30:00Z"
    }
  ]
}

获取销售记录

GET /gumroad/v2/sales/{sale_id}

订阅者操作

列出订阅者

GET /gumroad/v2/products/{product_id}/subscribers

获取订阅者

GET /gumroad/v2/subscribers/{subscriber_id}

响应：

{
  "success": true,
  "subscriber": {
    "id": "sub123",
    "product_id": "prod123",
    "product_name": "Monthly Subscription",
    "user_id": "user123",
    "user_email": "subscriber@example.com",
    "status": "alive",
    "created_at": "2026-01-01T00:00:00Z"
  }
}

许可证操作

验证许可证

POST /gumroad/v2/licenses/verify
Content-Type: application/x-www-form-urlencoded

product_id={product_id}&license_key={license_key}

参数：

产品ID- 产品ID（必需）
许可证密钥- 待验证的许可证密钥（必需）
增加使用次数- 是否增加使用次数（默认值：true）

响应（成功）：

{
  "success": true,
  "uses": 1,
  "purchase": {
    "seller_id": "seller123",
    "product_id": "prod123",
    "product_name": "My Product",
    "permalink": "abc",
    "email": "customer@example.com",
    "license_key": "ABC-123-DEF",
    "quantity": 1,
    "created_at": "2026-01-15T00:00:00Z"
  }
}

响应（失败）：

{
  "success": false,
  "message": "That license does not exist for the provided product."
}

启用许可证

PUT /gumroad/v2/licenses/enable
Content-Type: application/x-www-form-urlencoded

product_id={product_id}&license_key={license_key}

禁用许可证

PUT /gumroad/v2/licenses/disable
Content-Type: application/x-www-form-urlencoded

product_id={product_id}&license_key={license_key}

减少许可证使用次数

PUT /gumroad/v2/licenses/decrement_uses_count
Content-Type: application/x-www-form-urlencoded

product_id={product_id}&license_key={license_key}

资源订阅（Webhooks）

订阅销售及其他事件通知

列出资源订阅

GET /gumroad/v2/resource_subscriptions?resource_name=sale

参数：

resource_name- 必需参数。可选值包括：sale（销售）、refund（退款）、dispute（争议）、dispute_won（争议胜诉）、cancellation（取消）、subscription_updated（订阅更新）、subscription_ended（订阅终止）、subscription_restarted（订阅重启）

响应：

{
  "success": true,
  "resource_subscriptions": [
    {
      "id": "wX43hzi-s7W4JfYFkxyeiQ==",
      "resource_name": "sale",
      "post_url": "https://example.com/webhook"
    }
  ]
}

删除资源订阅

DELETE /gumroad/v2/resource_subscriptions/{resource_subscription_id}

响应：

{
  "success": true,
  "message": "The resource_subscription was deleted successfully."
}

变体类别

列出变体类别

GET /gumroad/v2/products/{product_id}/variant_categories

获取变体类别

GET /gumroad/v2/products/{product_id}/variant_categories/{variant_category_id}

创建变体类别

POST /gumroad/v2/products/{product_id}/variant_categories
Content-Type: application/x-www-form-urlencoded

title=Size

删除变体类别

DELETE /gumroad/v2/products/{product_id}/variant_categories/{variant_category_id}

变体

列出变体

GET /gumroad/v2/products/{product_id}/variant_categories/{variant_category_id}/variants

创建变体

POST /gumroad/v2/products/{product_id}/variant_categories/{variant_category_id}/variants
Content-Type: application/x-www-form-urlencoded

name=Large&price_difference=200

更新变体

PUT /gumroad/v2/products/{product_id}/variant_categories/{variant_category_id}/variants/{variant_id}
Content-Type: application/x-www-form-urlencoded

name=Extra%20Large

删除变体

DELETE /gumroad/v2/products/{product_id}/variant_categories/{variant_category_id}/variants/{variant_id}

自定义字段

列出自定义字段

GET /gumroad/v2/products/{product_id}/custom_fields

创建自定义字段

POST /gumroad/v2/products/{product_id}/custom_fields
Content-Type: application/x-www-form-urlencoded

name=Company%20Name&required=true

更新自定义字段

PUT /gumroad/v2/products/{product_id}/custom_fields/{name}
Content-Type: application/x-www-form-urlencoded

required=false

删除自定义字段

DELETE /gumroad/v2/products/{product_id}/custom_fields/{name}

分页

Gumroad 对返回列表的端点使用基于页面的分页：

GET /gumroad/v2/sales?page=1
GET /gumroad/v2/sales?page=2

持续递增页码，直到收到空列表。

代码示例

JavaScript

const response = await fetch(
  'https://gateway.maton.ai/gumroad/v2/products',
  {
    headers: {
      'Authorization': `Bearer ${process.env.MATON_API_KEY}`
    }
  }
);
const data = await response.json();

Python

import os
import requests

response = requests.get(
    'https://gateway.maton.ai/gumroad/v2/products',
    headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}
)
data = response.json()

Python（验证许可证）

import os
import requests

response = requests.post(
    'https://gateway.maton.ai/gumroad/v2/licenses/verify',
    headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'},
    data={
        'product_id': 'your_product_id',
        'license_key': 'CUSTOMER-LICENSE-KEY'
    }
)
result = response.json()
if result['success']:
    print(f"License valid! Uses: {result['uses']}")
else:
    print(f"Invalid: {result['message']}")

注意

所有响应都包含一个success布尔字段
无法通过API创建产品——必须通过Gumroad网站创建产品
POST/PUT请求使用application/x-www-form-urlencoded内容类型（而非JSON）
价格单位为美分（例如：500 = 5.00美元）
许可证密钥不区分大小写
资源订阅webhook会向您指定的URL发送POST请求
重要提示：当通过管道将curl输出传递给jq或其他命令时，某些shell环境中$MATON_API_KEY等环境变量可能无法正确展开

错误处理

状态码	含义
400	缺少Gumroad连接或请求错误
401	Maton API密钥无效或缺失
404	资源未找到（返回`success: false`）
429	请求频率受限
4xx/5xx 错误	来自 Gumroad API 的透传错误

Gumroad 错误通常返回 HTTP 404 并附带 JSON 响应体：

{
  "success": false,
  "message": "Error description"
}

故障排除：API 密钥问题

检查MATON_API_KEY环境变量是否已设置：

echo $MATON_API_KEY

通过列出连接来验证 API 密钥是否有效：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.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

故障排除：无效的应用名称

确保您的 URL 路径以gumroad开头。例如：

正确示例：https://gateway.maton.ai/gumroad/v2/user
错误示例：https://gateway.maton.ai/v2/user

资源

免责申明

部分文章来自各大搜索引擎，如有侵权，请与我联系删除。

打赏

文章底部电脑广告

手机广告位-内容正文底部

标签

上一篇：serper 下一篇：Zoho Books

Gumroad

Gumroad

快速入门

基础URL

认证

获取您的API密钥

连接管理

列出连接

创建连接

获取连接

删除连接

指定连接

API 参考

用户信息

获取当前用户

产品操作

列出产品

获取产品

更新产品

启用/禁用产品

删除产品

优惠码操作

列出优惠码

获取优惠码

创建优惠码

更新优惠码

删除优惠码

销售操作

列出销售记录

获取销售记录

订阅者操作

列出订阅者

获取订阅者

许可证操作

验证许可证

启用许可证

禁用许可证

减少许可证使用次数

资源订阅（Webhooks）

列出资源订阅

删除资源订阅

变体类别

列出变体类别

获取变体类别

创建变体类别

删除变体类别

变体

列出变体

创建变体

更新变体

删除变体

自定义字段

列出自定义字段

创建自定义字段

更新自定义字段

删除自定义字段

分页

代码示例

JavaScript

Python

Python（验证许可证）

注意

错误处理

故障排除：API 密钥问题

故障排除：无效的应用名称

资源

相关文章

推荐文章

热门浏览

标签列表