RecurringApplicationCharge::InvalidTransitionError when canceling app subscription

GraphQL Admin API Troubleshooting
1

Issue Description

I’m encountering a RecurringApplicationCharge::InvalidTransitionError when trying to cancel a Shopify app subscription programmatically. This error occurs when calling the appSubscriptionCancel GraphQL mutation.

Error Details

Subscription cancellation failed: RecurringApplicationCharge::InvalidTransitionError

Full Error Stack:

Error canceling subscription: Error: Subscription cancellation failed: RecurringApplicationCharge::InvalidTransitionError
at cancelSubscription (file:///app/build/server/assets/server-build-D7Gew7pK.js:5120:13)

Code Implementation

I’m using the following GraphQL mutation to cancel subscriptions:

mutation AppSubscriptionCancel($id: ID!, $prorate: Boolean) {
  appSubscriptionCancel(id: $id, prorate: $prorate) {
    userErrors {
      field
      message
    }
    appSubscription {
      id
      status
    }
  }
}

Variables:

  • id: The subscription ID (e.g., “gid://shopify/AppSubscription/123456789”)
  • prorate: Boolean (true/false)

Subscription Structure

The subscription being canceled has:

  • Recurring pricing: $19.99/month (EVERY_30_DAYS)
  • Usage pricing: 10% of recovered cart value (capped at $100)
  • Trial period: 3 days
  • Status: ACTIVE (before cancellation attempt)

Questions for the Community

  1. What causes this InvalidTransitionError?

    • Is it related to the subscription’s current state?
    • Are there specific conditions that prevent cancellation?

  2. Subscription State Validation

    • Should I check the subscription status before attempting cancellation?
    • What are the valid states for cancellation?

  3. Error Handling Best Practices

    • How should I handle this specific error in production?
    • Should I implement retry logic or show a specific user message?

Environment

  • Platform: Shopify App (Node.js/Remix)
  • API Version: 2024-01
  • Authentication: Admin API access token
  • Subscription Type: Recurring + Usage-based pricing
2

Hi @toprakgundogdu

This error should only appear if you’re attempting to cancel a subscription which has a status of CANCELLED , EXPIRED , DECLINED , or FROZEN will result in an error.

Should I check the subscription status before attempting cancellation?

Yes - you can check by querying appSubscription:

query GetAppSubscriptionStatus {
  appSubscription(id: "gid://shopify/AppSubscription/123456789") {
    id
    status
  }
}

If you receive a RecurringApplicationCharge::InvalidTransitionError in production, inform the merchant that the subscription cannot be canceled because it is not in an active state. Do not implement retry logic for this error, as it is not transient. Instead, check the subscription status and only attempt cancellation if appropriate.

3

I checked the subscription status but it was PENDING. Is that a status that results in an error?