跳转到主要内容
POST
Create a product
请使用属于目标组织、且为全部权限或勾选了 products:products:write 权限的 API 密钥进行认证。只有 Owner 和 Admin 角色可以授予该权限。
  • 参数与控制台中创建产品相同:一个产品,一个价格。
  • 与控制台不同,该接口不会创建支付链接。如需可分享的链接,请为该产品创建支付链接,或通过结账会话销售该价格(见下文)。
  • 必填请求头 Idempotency-Key(1–255 个 ASCII 字符,范围为 0x21 至 0x7E,不允许空格),规则与结账会话相同。相同的键加相同的请求体,返回第一次创建的产品(201),不会重复创建。相同的键但请求体不同,返回 409。如果该键创建的产品之后被删除,重试也会返回 409,请换一个新的键。
  • pricingType 为 ONE_TIME 或 SUBSCRIPTION。pricing 是以主单位表示的字符串,如 "19.99"。不传 pricing 即为灵活的“自定义金额”价格,仅限 ONE_TIME,此时 minAmount 和 maxAmount 可选。
  • SUBSCRIPTION 价格必须提供 billingInterval(DAY、MONTH 或 YEAR)。billingIntervalCount 可选,默认为 1。
  • status 为 PUBLISHED(默认)、DRAFT 或 ARCHIVED。DRAFT 状态的产品之后无法发布或归档。如果暂时不想上架,请以 ARCHIVED 状态创建,准备好后再发布。
  • 未知字段会被拒绝,返回 400。
  • 销售固定价格时,请将返回的 pricing.pricingId 作为 pricingId 传给创建结账会话。结账会话不支持灵活金额;灵活金额请创建支付链接。

授权

X-API-Key
string
header
必填

Merchant API key (format: ak_BASE64)

请求头

Idempotency-Key
string
必填

Unique creation request key: 1-255 ASCII characters in the range 0x21-0x7E (no spaces or control characters)

Required string length: 1 - 255

请求体

application/json

Product and price

name
string
必填

Product name

pricingType
enum<string>
必填
可用选项:
SUBSCRIPTION,
ONE_TIME
currency
string
必填

Currency code, for example USD

description
string
pricing
string

Price in major units, for example "19.99". Omit for a flexible (pay what you want) price, which is ONE_TIME only.

minAmount
number

Optional minimum for a flexible price (ONE_TIME only)

maxAmount
number

Optional maximum for a flexible price (ONE_TIME only)

pricingName
string

Name of the price

billingInterval
enum<string>
可用选项:
DAY,
MONTH,
YEAR
billingIntervalCount
integer

Number of intervals between charges (SUBSCRIPTION). Defaults to 1.

status
enum<string>
默认值:PUBLISHED
可用选项:
PUBLISHED,
DRAFT,
ARCHIVED

响应

Created

data
object
error
object
message
string
success
boolean