API reference Memberships & checkout Read subscription batch POST /api/v1/subscriptions/batches/read
Read batchId and each group's status, quote, failure and management URL. This read does not accept a quote or start another provider operation.
SDK 0.0.1 Updated Oct 14, 2026
On this page
Make the request Read batchId and each group's status, quote, failure and management URL. This read does not accept a quote or start another provider operation.
Credential Server API key only. Call from your trusted backend.
Permission billing:readSet the base URL and App ID from SDK setup. These examples use placeholders and do not execute requests. Never put a server key in browser code.
1 curl -X POST "$GROOVE_BASE_URL/api/v1/subscriptions/batches/read" \2 -H "Authorization: Bearer $GROOVE_SECRET_KEY" \ 3 -H "X-Groove-Project: $GROOVE_PROJECT_ID" \ 4 -H "X-Groove-Environment: sandbox" \ 5 -H "Content-Type: application/json" \ 6 -d '{ 7 "customerId" : "00000000-0000-4000-8000-000000000001" , 8 "batchId" : "00000000-0000-4000-8000-000000000001" 9 } '
The response tab lists field types, not an example payload. Actual values depend on customer state.
Request parameters JSON body batchIduuid Required The batchId value for this operation. Its accepted type and constraints are listed above and below.
customerIduuid Required Indiana customer ID mapped from a verified identity on the server. Omit for customer-token calls, which use the token-bound customer.
Response fields Successful responses include requestId and scope. Use the actual business status or accepted field to determine the result. Optional fields are omitted when unavailable.
HTTP 200 · application/json requestIduuid Required Server-generated HTTP request UUID. Include it when reporting a failed request.
scopeobject Required The App and environment of this response. Headers only verify scope; they cannot switch key scope.
projectIdstring Required App ID bound to the credential.
minLength: 1
environmentenum Required Separate data scope: sandbox or live.
"sandbox""live"
batchobject Required The batch value for this operation. Its accepted type and constraints are listed above and below.
batchIduuid Required The batchId value for this operation. Its accepted type and constraints are listed above and below.
readyboolean Required The ready value for this operation. Its accepted type and constraints are listed above and below.
statusenum Required The status value for this operation. Its accepted type and constraints are listed above and below.
"prepared""cancelled""expired""pending""partial""effective""action_required"
createdAtdate-time Required ISO 8601 UTC time when the record was created.
acceptedAtdate-time | null Required The acceptedAt value for this operation. Its accepted type and constraints are listed above and below.
groupsarray Required The groups value for this operation. Its accepted type and constraints are listed above and below.
minItems: 1 · maxItems: 100
operationIduuid Required Business operation UUID. Subscription execution references operationId from previewAttach; balance refunds reference the original consumption.
membershipIdsarray Required The membershipIds value for this operation. Its accepted type and constraints are listed above and below.
minItems: 1 · maxItems: 20
providerenum Required The provider value for this operation. Its accepted type and constraints are listed above and below.
"stripe""apple""google"
actionenum Required Business action. Target fields and quantity requirements vary by action; see the request structure and example.
"cancel""uncancel"
timingenum Required Immediate or end-of-cycle timing, only for supported plan-change actions.
"immediate""renewal"
statusenum Required The status value for this operation. Its accepted type and constraints are listed above and below.
"prepared""confirmed""pending""scheduled""effective""cancelled""failed""store_action_required"
quoteobject | null Required The quote value for this operation. Its accepted type and constraints are listed above and below.
carryOverBalancesobject Optional The carryOverBalances value for this operation. Its accepted type and constraints are listed above and below.
carryOverUsagesobject Optional The carryOverUsages value for this operation. Its accepted type and constraints are listed above and below.
operationIduuid Required Business operation UUID. Subscription execution references operationId from previewAttach; balance refunds reference the original consumption.
membershipIduuid Required The membershipId value for this operation. Its accepted type and constraints are listed above and below.
productVersionIduuid Required The productVersionId value for this operation. Its accepted type and constraints are listed above and below.
timingenum Required Immediate or end-of-cycle timing, only for supported plan-change actions.
"immediate""renewal"
effectiveAtdate-time Required The effectiveAt value for this operation. Its accepted type and constraints are listed above and below.
expiresAtdate-time Required ISO 8601 UTC expiry. Expired sessions and reservations cannot be reused.
currencyenum Required Currency code supported by the published price.
"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 Required The creditMinor value for this operation. Its accepted type and constraints are listed above and below.
min: 0 · max: 100000000
debitMinorinteger Required The debitMinor value for this operation. Its accepted type and constraints are listed above and below.
min: 0 · max: 100000000
discountMinorinteger Required The discountMinor value for this operation. Its accepted type and constraints are listed above and below.
min: 0 · max: 100000000
taxMinorinteger Required The taxMinor value for this operation. Its accepted type and constraints are listed above and below.
min: 0 · max: 100000000
totalMinorinteger Required The totalMinor value for this operation. Its accepted type and constraints are listed above and below.
min: 0 · max: 100000000
retainedProductVersionIdsarray Required The retainedProductVersionIds value for this operation. Its accepted type and constraints are listed above and below.
maxItems: 19
managementUrluri | null Required The managementUrl value for this operation. Its accepted type and constraints are listed above and below.
failureCodeenum | null Required The failureCode value for this operation. Its accepted type and constraints are listed above and below.
Handle errors Common failures Code Recovery UNAUTHENTICATED Verify the key or refresh the expired customer token once. FORBIDDEN Check current key permissions and customer access. INVALID_REQUEST Check field types, UUIDs, decimal strings and mutually exclusive fields. SCOPE_MISMATCH Use the App and environment bound to the credential.
Common failures
UNAUTHENTICATED
Recovery Verify the key or refresh the expired customer token once. FORBIDDEN
Recovery Check current key permissions and customer access. INVALID_REQUEST
Recovery Check field types, UUIDs, decimal strings and mutually exclusive fields. SCOPE_MISMATCH
Recovery Use the App and environment bound to the credential. Related:All request and error conventions · Back to endpoint index