预览套餐购买
POST/api/v1/subscriptions/preview-attach
按固定版本和币种保存最长 24 小时的报价，不创建订单或发放付费权益。同一 requestId 重试返回原报价。仅记录模式下，报价的 execution 是商家后端用自己的 Stripe Key 创建 Checkout Session 的指令（Stripe Price、优惠、试用天数、到期时间和必须原样复制的 metadata）；购买都根据已验签的 Stripe 通知记录。仅记录模式不出售用量后付费的 Price（周期结束时按用量收费），含这类 Price 的套餐返回 NOT_CONFIGURED。多个付费 Stripe 套餐须同币种、同收费周期和相同试用条件。seatQuantities 按 License 计划 ID 设定席位总数，超出包含席位的部分按 License 价格随购买计费；不需要卡的试用不能带付费席位。可传已领取的 offerId，报价冻结优惠条款与逐套餐金额，最多一张券。自动税额由 Stripe 确认。
API v1更新于
发起请求
按固定版本和币种保存最长 24 小时的报价，不创建订单或发放付费权益。同一 requestId 重试返回原报价。仅记录模式下，报价的 execution 是商家后端用自己的 Stripe Key 创建 Checkout Session 的指令（Stripe Price、优惠、试用天数、到期时间和必须原样复制的 metadata）；购买都根据已验签的 Stripe 通知记录。仅记录模式不出售用量后付费的 Price（周期结束时按用量收费），含这类 Price 的套餐返回 NOT_CONFIGURED。多个付费 Stripe 套餐须同币种、同收费周期和相同试用条件。seatQuantities 按 License 计划 ID 设定席位总数，超出包含席位的部分按 License 价格随购买计费；不需要卡的试用不能带付费席位。可传已领取的 offerId，报价冻结优惠条款与逐套餐金额，最多一张券。自动税额由 Stripe 确认。
- 调用凭据
- 服务端 API Key 或客户 Token。客户调用不能选择其他客户。
- 所需权限
billing:read
base URL 和 App ID 来自 SDK 接入页。示例使用占位值，不会执行请求。服务端 Key 不可放入浏览器。
1curl -X POST "$INDIANA_BASE_URL/api/v1/subscriptions/preview-attach" \2 -H "Authorization: Bearer $INDIANA_CUSTOMER_TOKEN" \3 -H "X-Indiana-Project: $INDIANA_PROJECT_ID" \4 -H "X-Indiana-Protocol: 0.5" \5 -H "X-Indiana-Environment: sandbox" \6 -H "Content-Type: application/json" \7 -d '{8 "requestId": "00000000-0000-4000-8000-000000000001",9 "plans": [10 {11 "productVersionId": "00000000-0000-4000-8000-000000000001"12 }13 ],14 "provider": "stripe",15 "currency": "USD"16}'
响应为示例，不代表已实际执行请求。
请求参数
JSON 请求体
requestIduuid必填你的业务请求 UUID；同一次操作重试复用，新的操作生成新值。
invoiceModeobject可选本次操作的 invoiceMode 值，类型和约束见字段标注。
展开子字段
enabledboolean必填本次操作的 enabled 值，类型和约束见字段标注。
enable_plan_immediatelyboolean可选本次操作的 enable_plan_immediately 值，类型和约束见字段标注。
default: false
finalizeboolean可选本次操作的 finalize 值，类型和约束见字段标注。
default: true
invoice_template_idstring可选本次操作的 invoice_template_id 值，类型和约束见字段标注。
net_terms_daysinteger可选本次操作的 net_terms_days 值，类型和约束见字段标注。
max: 9007199254740991
entityIduuid可选当前客户范围内的实体 ID；只用于已配置的实体和许可功能。
billingSubscriptionIduuid可选本次操作的 billingSubscriptionId 值，类型和约束见字段标注。
newBillingSubscriptiontrue可选仅 Stripe 可设为 true，强制新建财务订阅，不能同时指定 billingSubscriptionId；仍校验跨渠道主套餐互斥。
offerIduuid可选当前客户已领取优惠的 ID；与 promotionCode 互斥。
nativeOfferobject可选本次操作的 nativeOffer 值，类型和约束见字段标注。
展开子字段
offerKindenum必填本次操作的 offerKind 值，类型和约束见字段标注。
查看允许值
"none""introductory""promotional"
offerIdstring | null必填当前客户已领取优惠的 ID；与 promotionCode 互斥。
discountMinorinteger必填本次操作的 discountMinor 值，类型和约束见字段标注。
min: 0 · max: 100000000
trialDaysinteger | null必填本次操作的 trialDays 值，类型和约束见字段标注。
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"
nativeOfferobject可选本次操作的 nativeOffer 值，类型和约束见字段标注。
展开子字段
offerKindenum必填本次操作的 offerKind 值，类型和约束见字段标注。
查看允许值
"none""introductory""promotional"
offerIdstring | null必填当前客户已领取优惠的 ID；与 promotionCode 互斥。
discountMinorinteger必填本次操作的 discountMinor 值，类型和约束见字段标注。
min: 0 · max: 100000000
trialDaysinteger | null必填本次操作的 trialDays 值，类型和约束见字段标注。
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}$
internal_feature_iduuid必填本次操作的 internal_feature_id 值，类型和约束见字段标注。
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 值，类型和约束见字段标注。
executionobject | null必填本次操作的 execution 值，类型和约束见字段标注。
展开子字段
invoiceModeobject可选本次操作的 invoiceMode 值，类型和约束见字段标注。
展开子字段
enabledboolean必填本次操作的 enabled 值，类型和约束见字段标注。
enable_plan_immediatelyboolean必填本次操作的 enable_plan_immediately 值，类型和约束见字段标注。
default: false
finalizeboolean必填本次操作的 finalize 值，类型和约束见字段标注。
default: true
invoice_template_idstring可选本次操作的 invoice_template_id 值，类型和约束见字段标注。
net_terms_daysinteger可选本次操作的 net_terms_days 值，类型和约束见字段标注。
max: 9007199254740991
appendobject可选本次操作的 append 值，类型和约束见字段标注。
展开子字段
subscriptionIdstring必填本次操作的 subscriptionId 值，类型和约束见字段标注。
pattern: ^sub_[A-Za-z0-9]+$
customerIdstring必填Indiana 客户 ID。服务端从已验证身份关联；客户 Token 调用时省略并使用 Token 绑定的客户。
pattern: ^cus_[A-Za-z0-9]+$
sourceItemsarray必填本次操作的 sourceItems 值，类型和约束见字段标注。
minItems: 1 · maxItems: 100
prorationDateinteger必填本次操作的 prorationDate 值，类型和约束见字段标注。
min: 0 · max: 9007199254740991
amountMinorinteger必填本次操作的 amountMinor 值，类型和约束见字段标注。
max: 9007199254740991
periodStartMsnumber必填本次操作的 periodStartMs 值，类型和约束见字段标注。
periodEndMsnumber必填本次操作的 periodEndMs 值，类型和约束见字段标注。
provider"stripe"必填本次操作的 provider 值，类型和约束见字段标注。
executorenum必填本次操作的 executor 值，类型和约束见字段标注。
查看允许值
"indiana""merchant"
accountIdstring必填本次操作的 accountId 值，类型和约束见字段标注。
pattern: ^acct_[A-Za-z0-9]+$
modeenum必填本次操作的 mode 值，类型和约束见字段标注。
查看允许值
"payment""subscription"
lineItemsarray必填本次操作的 lineItems 值，类型和约束见字段标注。
minItems: 1 · maxItems: 100
展开子字段
pricestring | null必填当前请求或现有计费币种的价格；不可用时 null，不改用其他币种。
quantityinteger必填业务数量按字段标注类型传入；积分操作用十进制字符串，避免浮点误差。quote／reserve／confirm／refund 要求正数；consume 可记录零费用事件。
min: 1 · max: 10000
priceIduuid必填本次操作的 priceId 值，类型和约束见字段标注。
productNamestring必填本次操作的 productName 值，类型和约束见字段标注。
minLength: 1 · maxLength: 80
amountMinorinteger必填本次操作的 amountMinor 值，类型和约束见字段标注。
min: 0 · max: 100000000
currencystring必填已发布价格支持的币种代码。
pattern: ^[a-z]{3}$
intervalenum必填本次操作的 interval 值，类型和约束见字段标注。
查看允许值
"week""month""year""one_off"
intervalCountinteger必填收费周期的次数：week 最多 156、month 最多 36、year 最多 3，省略为 1；free 和 one_time 不接受。额度重置周期独立。
min: 1 · max: 52
slotenum必填本次操作的 slot 值，类型和约束见字段标注。
查看允许值
"stripe_price_id""stripe_empty_price_id"
tiersobject | null必填本次操作的 tiers 值，类型和约束见字段标注。
discountsarray必填本次操作的 discounts 值，类型和约束见字段标注。
maxItems: 1
展开子字段
couponstring必填本次操作的 coupon 值，类型和约束见字段标注。
pattern: ^[A-Za-z0-9_-]{1,200}$
termsobject必填本次操作的 terms 值，类型和约束见字段标注。
trialPeriodDaysinteger | null必填本次操作的 trialPeriodDays 值，类型和约束见字段标注。
metadataobject必填本次操作的 metadata 值，类型和约束见字段标注。
展开子字段
grooveCheckoutIduuid必填本次操作的 grooveCheckoutId 值，类型和约束见字段标注。
grooveCustomerIduuid必填本次操作的 grooveCustomerId 值，类型和约束见字段标注。
expiresAtdate-time必填ISO 8601 UTC 到期时间；会话和预占到期后不能继续使用。
处理错误
常见失败| 错误码 | 处理方式 |
|---|
| UNAUTHENTICATED | 核对 Key，或将过期客户 Token 重新签发一次。 |
| FORBIDDEN | 核对当前 Key 权限与客户访问范围。 |
| INVALID_REQUEST | 检查字段类型、UUID、十进制字符串和互斥字段。 |
| SCOPE_MISMATCH | 使用凭据绑定的 App 和环境。 |
常见失败
UNAUTHENTICATED
- 处理方式
- 核对 Key，或将过期客户 Token 重新签发一次。
FORBIDDEN
- 处理方式
- 核对当前 Key 权限与客户访问范围。
INVALID_REQUEST
- 处理方式
- 检查字段类型、UUID、十进制字符串和互斥字段。
SCOPE_MISMATCH
- 处理方式
- 使用凭据绑定的 App 和环境。
相关:完整请求与错误约定·返回接口索引