预览套餐购买
POST/api/v1/subscriptions/preview-attach
按固定版本、币种和席位数量保存 15 分钟报价，不创建订单或发放付费权益。同一 requestId 重试返回原报价。当前独立执行支持单套餐 Stripe／免费购买，以及同连接、币种、收费周期的多个付费 Stripe 套餐；多套餐购买仍要求服务端支持的共同收费条件；原生购买需要固定 SKU、宿主商店操作及验单，不能沿用 Stripe 可变数量。新购 Stripe 订阅可传已领取的 offerId，报价冻结优惠条款与逐套餐金额；attach 仅接受 operationId，不能换券复用报价。首次 Checkout 最多一张券。自动税额由渠道确认。
SDK 0.0.1更新于
发起请求
按固定版本、币种和席位数量保存 15 分钟报价，不创建订单或发放付费权益。同一 requestId 重试返回原报价。当前独立执行支持单套餐 Stripe／免费购买，以及同连接、币种、收费周期的多个付费 Stripe 套餐；多套餐购买仍要求服务端支持的共同收费条件；原生购买需要固定 SKU、宿主商店操作及验单，不能沿用 Stripe 可变数量。新购 Stripe 订阅可传已领取的 offerId，报价冻结优惠条款与逐套餐金额；attach 仅接受 operationId，不能换券复用报价。首次 Checkout 最多一张券。自动税额由渠道确认。
- 调用凭据
- 服务端 API Key 或客户 Token。客户调用不能选择其他客户。
- 所需权限
billing:read
base URL 和 App ID 来自 SDK 接入页。示例使用占位值，不会执行请求。服务端 Key 不可放入浏览器。
1curl -X POST "$GROOVE_BASE_URL/api/v1/subscriptions/preview-attach" \2 -H "Authorization: Bearer $GROOVE_CUSTOMER_TOKEN" \3 -H "X-Groove-Project: $GROOVE_PROJECT_ID" \4 -H "X-Groove-Environment: sandbox" \5 -H "Content-Type: application/json" \6 -d '{7 "requestId": "00000000-0000-4000-8000-000000000001",8 "plans": [9 {10 "productVersionId": "00000000-0000-4000-8000-000000000001"11 }12 ],13 "provider": "stripe",14 "currency": "USD"15}'
响应为示例，不代表已实际执行请求。
请求参数
JSON 请求体
requestIduuid必填你的业务请求 UUID；同一次操作重试复用，新的操作生成新值。
entityIduuid可选当前客户范围内的实体 ID；只用于已配置的实体和许可功能。
billingSubscriptionIduuid可选本次操作的 billingSubscriptionId 值，类型和约束见字段标注。
newBillingSubscriptiontrue可选仅 Stripe 可设为 true，强制新建财务订阅，不能同时指定 billingSubscriptionId；仍校验跨渠道主套餐互斥。
offerIduuid可选当前客户已领取优惠的 ID；与 promotionCode 互斥。
plansarray必填本次操作的 plans 值，类型和约束见字段标注。
minItems: 1 · maxItems: 20
展开子字段
productVersionIduuid必填本次操作的 productVersionId 值，类型和约束见字段标注。
seatQuantitiesobject可选本次操作的 seatQuantities 值，类型和约束见字段标注。
featureQuantitiesobject可选本次操作的 featureQuantities 值，类型和约束见字段标注。
providerenum必填本次操作的 provider 值，类型和约束见字段标注。
查看允许值
"stripe""apple""google"
currencyenum必填已发布价格支持的币种代码。
查看允许值
"USD""EUR""CNY""GBP""JPY""CAD""AUD""NZD""CHF""HKD""SGD""KRW""INR""BRL""MXN""TWD""THB""IDR""MYR""PHP""VND""ZAR""AED""SAR""SEK""NOK""DKK""PLN""CZK""HUF""ILS""TRY""RON"
customerIduuid可选Indiana 客户 ID。服务端从已验证身份关联；客户 Token 调用时省略并使用 Token 绑定的客户。
响应字段
成功响应包含 requestId 和 scope。结合实际业务状态或 accepted 判断操作结果；可选字段不可用时省略。
HTTP 200 · application/json
requestIduuid必填服务端生成的 HTTP 请求 UUID，排查请求时提供这个值。
scopeobject必填响应实际所属的 App 和环境。Header 只能核对，不能切换 Key 范围。
展开子字段
projectIdstring必填凭据绑定的 App ID。
minLength: 1
environmentenum必填独立数据范围：sandbox 或 live。
查看允许值
"sandbox""live"
quoteobject必填本次操作的 quote 值，类型和约束见字段标注。
展开子字段
operationIduuid必填业务操作 UUID；订阅执行引用 previewAttach 返回的 operationId，余额退款引用原消费操作。
entityIduuid | null必填当前客户范围内的实体 ID；只用于已配置的实体和许可功能。
billingSubscriptionIduuid | null必填本次操作的 billingSubscriptionId 值，类型和约束见字段标注。
discountobject | null必填本次操作的 discount 值，类型和约束见字段标注。
展开子字段
offerIduuid必填当前客户已领取优惠的 ID；与 promotionCode 互斥。
couponIduuid必填当前 App 和环境中的优惠券 UUID。
discountobject | object必填本次操作的 discount 值，类型和约束见字段标注。
展开子字段
type"percent" | "amount"必填本次操作的 type 值，类型和约束见字段标注。
percentOffinteger可选本次操作的 percentOff 值，类型和约束见字段标注。
min: 1 · max: 100
amountOffCentsinteger可选本次操作的 amountOffCents 值，类型和约束见字段标注。
min: 1 · max: 100000000
currencyenum可选已发布价格支持的币种代码。
查看允许值
"USD""EUR""CNY""GBP""JPY""CAD""AUD""NZD""CHF""HKD""SGD""KRW""INR""BRL""MXN""TWD""THB""IDR""MYR""PHP""VND""ZAR""AED""SAR""SEK""NOK""DKK""PLN""CZK""HUF""ILS""TRY""RON"
durationobject | object | object必填本次操作的 duration 值，类型和约束见字段标注。
展开子字段
type"once" | "repeating" | "forever"必填本次操作的 type 值，类型和约束见字段标注。
monthsinteger可选本次操作的 months 值，类型和约束见字段标注。
min: 1 · max: 36
amountMinorinteger必填本次操作的 amountMinor 值，类型和约束见字段标注。
min: 0 · max: 100000000
allocationsarray必填本次规则计算或账本操作涉及的余额分配明细。
minItems: 1 · maxItems: 20
展开子字段
productVersionIduuid必填本次操作的 productVersionId 值，类型和约束见字段标注。
amountMinorinteger必填本次操作的 amountMinor 值，类型和约束见字段标注。
min: 0 · max: 100000000
expiresAtdate-time必填ISO 8601 UTC 到期时间；会话和预占到期后不能继续使用。
chargeobject | null必填本次操作的 charge 值，类型和约束见字段标注。
展开子字段
effectiveAtdate-time必填本次操作的 effectiveAt 值，类型和约束见字段标注。
periodEndsAtdate-time必填本次操作的 periodEndsAt 值，类型和约束见字段标注。
debitMinorinteger必填本次操作的 debitMinor 值，类型和约束见字段标注。
min: 0 · max: 100000000
discountMinorinteger必填本次操作的 discountMinor 值，类型和约束见字段标注。
min: 0 · max: 100000000
taxMinorinteger必填本次操作的 taxMinor 值，类型和约束见字段标注。
min: 0 · max: 100000000
totalMinorinteger必填本次操作的 totalMinor 值，类型和约束见字段标注。
min: 0 · max: 100000000
expiresAtdate-time必填ISO 8601 UTC 到期时间；会话和预占到期后不能继续使用。
providerenum必填本次操作的 provider 值，类型和约束见字段标注。
查看允许值
"stripe""apple""google"
currencyenum必填已发布价格支持的币种代码。
查看允许值
"USD""EUR""CNY""GBP""JPY""CAD""AUD""NZD""CHF""HKD""SGD""KRW""INR""BRL""MXN""TWD""THB""IDR""MYR""PHP""VND""ZAR""AED""SAR""SEK""NOK""DKK""PLN""CZK""HUF""ILS""TRY""RON"
linesarray必填本次操作的 lines 值，类型和约束见字段标注。
minItems: 1 · maxItems: 20
展开子字段
lineIduuid必填本次操作的 lineId 值，类型和约束见字段标注。
productVersionIduuid必填本次操作的 productVersionId 值，类型和约束见字段标注。
productNamestring必填本次操作的 productName 值，类型和约束见字段标注。
minLength: 1 · maxLength: 80
intervalenum必填本次操作的 interval 值，类型和约束见字段标注。
查看允许值
"free""week""month""year""one_time"
intervalCountinteger可选收费周期的次数：week 最多 156、month 最多 36、year 最多 3，省略为 1；free 和 one_time 不接受。额度重置周期独立。
min: 1 · max: 156
baseAmountMinorinteger必填本次操作的 baseAmountMinor 值，类型和约束见字段标注。
min: 0 · max: 100000000
seatsarray必填本次操作的 seats 值，类型和约束见字段标注。
maxItems: 20
展开子字段
keystring必填本次操作的 key 值，类型和约束见字段标注。
minLength: 1 · maxLength: 64 · pattern: ^[a-z][a-z0-9_]*$
quantityinteger必填业务数量按字段标注类型传入；积分操作用十进制字符串，避免浮点误差。quote／reserve／confirm／refund 要求正数；consume 可记录零费用事件。
min: 0 · max: 10000
includedQuantityinteger必填本次操作的 includedQuantity 值，类型和约束见字段标注。
min: 0 · max: 10000
maximumQuantityinteger必填本次操作的 maximumQuantity 值，类型和约束见字段标注。
min: 0 · max: 10000
unitAmountMinorinteger必填本次操作的 unitAmountMinor 值，类型和约束见字段标注。
min: 0 · max: 100000000
prepaidarray可选本次操作的 prepaid 值，类型和约束见字段标注。
maxItems: 100
展开子字段
itemKeystring必填本次操作的 itemKey 值，类型和约束见字段标注。
pattern: ^paid:feature:[a-f0-9]{8}-[a-f0-9]{4}-[1-8][a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$
entitlementVersionIduuid必填本次操作的 entitlementVersionId 值，类型和约束见字段标注。
includedAmountstring必填本次操作的 includedAmount 值，类型和约束见字段标注。
pattern: ^(0|[1-9]\d{0,11})(\.\d{1,6})?$
quantityinteger必填业务数量按字段标注类型传入；积分操作用十进制字符串，避免浮点误差。quote／reserve／confirm／refund 要求正数；consume 可记录零费用事件。
min: 0 · max: 10000
termsobject必填本次操作的 terms 值，类型和约束见字段标注。
pricingobject可选本次操作的 pricing 值，类型和约束见字段标注。
unitAmountMinorinteger必填本次操作的 unitAmountMinor 值，类型和约束见字段标注。
min: 0 · max: 100000000
productIdstring | null必填本次操作的 productId 值，类型和约束见字段标注。
priceIdstring | null必填本次操作的 priceId 值，类型和约束见字段标注。
catalogAmountMinorinteger必填本次操作的 catalogAmountMinor 值，类型和约束见字段标注。
min: 0 · max: 100000000
trialobject | null必填本次操作的 trial 值，类型和约束见字段标注。
展开子字段
daysinteger必填本次操作的 days 值，类型和约束见字段标注。
min: 1 · max: 730
cardRequiredboolean必填本次操作的 cardRequired 值，类型和约束见字段标注。
catalogAmountMinorinteger必填本次操作的 catalogAmountMinor 值，类型和约束见字段标注。
min: 0 · max: 100000000
automaticTaxboolean必填本次操作的 automaticTax 值，类型和约束见字段标注。
处理错误
常见失败| 错误码 | 处理方式 |
|---|
| UNAUTHENTICATED | 核对 Key，或将过期客户 Token 重新签发一次。 |
| FORBIDDEN | 核对当前 Key 权限与客户访问范围。 |
| INVALID_REQUEST | 检查字段类型、UUID、十进制字符串和互斥字段。 |
| SCOPE_MISMATCH | 使用凭据绑定的 App 和环境。 |
常见失败
UNAUTHENTICATED
- 处理方式
- 核对 Key，或将过期客户 Token 重新签发一次。
FORBIDDEN
- 处理方式
- 核对当前 Key 权限与客户访问范围。
INVALID_REQUEST
- 处理方式
- 检查字段类型、UUID、十进制字符串和互斥字段。
SCOPE_MISMATCH
- 处理方式
- 使用凭据绑定的 App 和环境。
相关:完整请求与错误约定·返回接口索引