We’ve migrated our documentation to a new site, which means some URLs have changed.
Subscriptions
Subscriptions
Breadcrumbs

Piano Subscription Testing in Sandbox vs. Production

Key Difference: Scheduled Tasks Do Not Run in Sandbox

In Production, Piano runs scheduled jobs that:

  • Attempt renewals and retries

  • Apply grace periods

  • Mark subscriptions/contracts as expired

  • Update subscription states used by access decisions

In Sandbox, these scheduled jobs are disabled by design. This can lead to confusing outcomes, such as access expiring while the subscription still appears "active," or renewal events never firing automatically.

What Will Not Happen Automatically in Sandbox

Recurring Payments and Auto-Renewals Don't Process

  • Subscriptions will process the initial purchase flow, but will not auto-renew in Sandbox.

  • Any testing that requires a real renewal attempt (including term changes that are realized through renewal cycles) must be done in Production.

Trial → Paid Transition Won't Happen Automatically

If you have an offer/term that includes an initial free/trial period followed by recurring charges, the automatic transition to paid billing will not occur in Sandbox.

Workaround: Manually renew (see Simulate a Renewal After a Trial Ends) to simulate the post-trial user experience.

Expiration State Updates May Not Occur

Because expiration/renewal jobs do not run:

  • A subscription may continue to show a status like active even when, logically, it should be expired.

  • Access rights can still expire based on configured durations, even if the subscription record doesn't update the way it would in Production.

  • Users may be blocked from re-subscribing because Sandbox still treats the subscription as active.

Workaround: Manually cancel the subscription in Sandbox to force it inactive/cancelled (see Simulate "Expiration").

How to Simulate Common Scenarios in Sandbox

Simulate "Expiration" So a User Can Re-Subscribe

Because Sandbox may not mark subscriptions expired automatically, you may need to manually force the state change:

  1. Open the user's subscription in the Piano management UI (subscription details).

  2. Cancel the subscription manually.

This typically changes the subscription status (e.g., to cancelled/inactive), allowing checkout flows that were blocked by an "active" subscription to proceed in Sandbox.

Simulate a Renewal After a Trial Ends

Because recurring charges don't run automatically, perform a manual renewal (for example, via the user's Identity Management / account dashboard flows available to you) to mimic the renewal experience and downstream integration behavior.

Verifying Subscription State via API in Sandbox

Because UI/status fields can be misleading in Sandbox, verify what the platform is returning via API.

List a User's Subscriptions

Example (JavaScript):

tp.api.callApi("/subscription/list", {}, function(data) { console.log(data) });

The returned status may still appear as active even when you would expect an expired state in Production, because Sandbox is not running the jobs that apply that transition.

Checking Auto-Renew Status

If you need to determine whether a subscription is set to renew (for example, to interpret a generic subscription_updated webhook), check auto-renew using:

  • /publisher/subscription/stats

This is especially useful when your integration needs to tell the difference between:

  • Auto-renew being turned off (subscription will expire at end of term)

  • Other updates (billing date changes, metadata updates, etc.)

When You Must Test in Production

Use Production (or a pre-production app within Production) when you need to validate any of the following end-to-end:

  • Actual scheduled renewal attempts and retries

  • Grace period handling

  • True expiration state transitions

  • Trial-to-paid conversion through real recurring billing logic

Practical Production Testing Pattern

To test subscription expiration safely:

  1. Create a short-term test offer (e.g., 1-day) or a free trial.

  2. Purchase with a dedicated test user.

  3. Let it expire naturally.

  4. Confirm Production runs the expiry job and transitions the subscription state accordingly.

If payments are involved, ensure your internal process covers refunds/voids as appropriate for your payment provider and testing policy.

Troubleshooting Checklist (Sandbox)

If a subscription didn't renew or expire as expected in Sandbox:

  1. Confirm the event is tied to scheduled processing

    • Renewals and expirations won't run automatically in Sandbox.

  2. If checkout is blocked due to an "active" subscription

    • Manually cancel the subscription in Sandbox to force a state change.

  3. Verify state via API

    • Use /subscription/list and (when relevant) /publisher/subscription/stats, but expect Sandbox to show states that would have been updated by scheduled jobs in Production.

  4. Test end-to-end in Production

    • For true renewal, expiration, and grace period behavior, use a Production or pre-production environment.

Last updated: