跳到正文
Indiana
控制台
文档
章节目录 / 读取批量订阅状态

读取批量订阅状态

POST/api/v1/subscriptions/batches/read

读取原 batchId 及逐组状态、报价、错误和管理入口。此读取本身不接受报价，也不触发新的渠道操作。

SDK 0.0.1更新于

发起请求

读取原 batchId 及逐组状态、报价、错误和管理入口。此读取本身不接受报价，也不触发新的渠道操作。

调用凭据
仅服务端 API Key。由可信后端调用。
所需权限
billing:read
base URL 和 App ID 来自 SDK 接入页。示例使用占位值，不会执行请求。服务端 Key 不可放入浏览器。
request.shShell
curl -X POST "$GROOVE_BASE_URL/api/v1/subscriptions/batches/read" \  -H "Authorization: Bearer $GROOVE_SECRET_KEY" \  -H "X-Groove-Project: $GROOVE_PROJECT_ID" \  -H "X-Groove-Environment: sandbox" \  -H "Content-Type: application/json" \  -d '{  "customerId": "00000000-0000-4000-8000-000000000001",  "batchId": "00000000-0000-4000-8000-000000000001"}'

响应选项卡列出字段类型，不是响应示例；实际值由客户状态决定。

请求参数

JSON 请求体

batchIduuid必填

本次操作的 batchId 值，类型和约束见字段标注。

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"

batchobject必填

本次操作的 batch 值，类型和约束见字段标注。

展开子字段
batchIduuid必填

本次操作的 batchId 值，类型和约束见字段标注。

readyboolean必填

本次操作的 ready 值，类型和约束见字段标注。

statusenum必填

本次操作的 status 值，类型和约束见字段标注。

查看允许值

"prepared""cancelled""expired""pending""partial""effective""action_required"

createdAtdate-time必填

记录创建时的 ISO 8601 UTC 时间。

acceptedAtdate-time | null必填

本次操作的 acceptedAt 值，类型和约束见字段标注。

groupsarray必填

本次操作的 groups 值，类型和约束见字段标注。

minItems: 1 · maxItems: 100

展开子字段
operationIduuid必填

业务操作 UUID；订阅执行引用 previewAttach 返回的 operationId，余额退款引用原消费操作。

membershipIdsarray必填

本次操作的 membershipIds 值，类型和约束见字段标注。

minItems: 1 · maxItems: 20

providerenum必填

本次操作的 provider 值，类型和约束见字段标注。

查看允许值

"stripe""apple""google"

actionenum必填

本次业务动作。不同动作的目标字段和数量要求不同，见请求结构与示例。

查看允许值

"cancel""uncancel"

timingenum必填

立即变更或在周期末变更；只用于契约允许的套餐变更动作。

查看允许值

"immediate""renewal"

statusenum必填

本次操作的 status 值，类型和约束见字段标注。

查看允许值

"prepared""confirmed""pending""scheduled""effective""cancelled""failed""store_action_required"

quoteobject | null必填

本次操作的 quote 值，类型和约束见字段标注。

展开子字段
carryOverBalancesobject可选

本次操作的 carryOverBalances 值，类型和约束见字段标注。

carryOverUsagesobject可选

本次操作的 carryOverUsages 值，类型和约束见字段标注。

operationIduuid必填

业务操作 UUID；订阅执行引用 previewAttach 返回的 operationId，余额退款引用原消费操作。

membershipIduuid必填

本次操作的 membershipId 值，类型和约束见字段标注。

productVersionIduuid必填

本次操作的 productVersionId 值，类型和约束见字段标注。

timingenum必填

立即变更或在周期末变更；只用于契约允许的套餐变更动作。

查看允许值

"immediate""renewal"

effectiveAtdate-time必填

本次操作的 effectiveAt 值，类型和约束见字段标注。

expiresAtdate-time必填

ISO 8601 UTC 到期时间；会话和预占到期后不能继续使用。

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"

creditMinorinteger必填

本次操作的 creditMinor 值，类型和约束见字段标注。

min: 0 · max: 100000000

debitMinorinteger必填

本次操作的 debitMinor 值，类型和约束见字段标注。

min: 0 · max: 100000000

discountMinorinteger必填

本次操作的 discountMinor 值，类型和约束见字段标注。

min: 0 · max: 100000000

taxMinorinteger必填

本次操作的 taxMinor 值，类型和约束见字段标注。

min: 0 · max: 100000000

totalMinorinteger必填

本次操作的 totalMinor 值，类型和约束见字段标注。

min: 0 · max: 100000000

retainedProductVersionIdsarray必填

本次操作的 retainedProductVersionIds 值，类型和约束见字段标注。

maxItems: 19

managementUrluri | null必填

本次操作的 managementUrl 值，类型和约束见字段标注。

failureCodeenum | null必填

本次操作的 failureCode 值，类型和约束见字段标注。

处理错误

常见失败
错误码处理方式
UNAUTHENTICATED核对 Key，或将过期客户 Token 重新签发一次。
FORBIDDEN核对当前 Key 权限与客户访问范围。
INVALID_REQUEST检查字段类型、UUID、十进制字符串和互斥字段。
SCOPE_MISMATCH使用凭据绑定的 App 和环境。

常见失败

  • UNAUTHENTICATED

    处理方式
    核对 Key，或将过期客户 Token 重新签发一次。

  • FORBIDDEN

    处理方式
    核对当前 Key 权限与客户访问范围。

  • INVALID_REQUEST

    处理方式
    检查字段类型、UUID、十进制字符串和互斥字段。

  • SCOPE_MISMATCH

    处理方式
    使用凭据绑定的 App 和环境。

相关:完整请求与错误约定·返回接口索引