Configure trials, manage them on your backend and distinguish default free plans from automatic trials.
SDK 0.0.1Updated
Trials through products and checkout nodes
Configure trial days, payment-method requirement and separate trial entitlements in a membership product, then save and publish.
Bind this App’s Stripe Sandbox price on the product payment-binding page. The Funnel checkout node references the fixed product version.
The server grants trial entitlements only after verifying actual trial activation. A zero-value trial invoice is not revenue; the first verified renewal payment establishes revenue and a paid period.
Stripe trials use published product terms and verified provider facts. Apple/Google trials require store eligibility, fixed SKUs and receipt verification. The store determines eligibility and periods; client assertions and Stripe rules cannot replace it. SDK availability does not certify real store trials.
Start, extend and end trials on the backend
The organizational SDK 0.0.1 includes manageSubscriptionTrial and readSubscriptionTrial. Use the quickstart’s backend groove client and map customerId from verified login; browsers cannot select another customer. Management requires billing:write; recovery reads require billing:read. This fragment requires the caller to durably retain the complete input and original requestId.
start uses productVersionId and optional Entity/days; extend uses membershipId and days; end uses membershipId. Days range from 1–730 and reason from 1–240 characters. Extensions calculate the deadline from frozen request time, not browser dates. Replay original input after a lost response, or recover the original operation when its operationId is known.
Free and Stripe use their own contracts and verification. Apple/Google return store_action_required and managementUrl, which do not prove a store trial changed. Shared subscriptions can involve multiple membershipIds; present the actual returned scope.
server/trial-management.ts · fragmentTypeScript
1const { trial } = await groove.manageSubscriptionTrial({2 customerId: verifiedCustomer.id,3 action: "extend",4 membershipId: verifiedMembershipId,5 days: 14,6 reason: "Approved trial extension",7 requestId: retainedRequestId,8});9// Save trial.operationId; read the same operation after a lost response.10const recovered = await groove.readSubscriptionTrial({11 customerId: verifiedCustomer.id,12 operationId: trial.operationId,13});14// effective means applied; store_action_required requires a store operation.15// In the latter case, return managementUrl to the authenticated host.
Default free plans and automatic trials
Configure a valid published default free plan per group; eligible customer creation or paid-contract termination assigns or restores it. Automatic cardless trials are a separate enabled group policy with a fixed product version, rather than a permanent free contract or recurring payment consent. Empty holdings are valid without configured policies. Read actual contracts and periods through readHoldings; registration time alone does not establish trial eligibility.