Understand QuickBooks Online subscription statuses

The status of end-users’ QuickBooks Online subscription impacts the way your app can use our API and related operations.

Build your app so it can anticipate subscription status changes and continue to work as expected.

Learn about subscription statuses

New users can start with a trial or subscribe to QuickBooks Online right away. Many users start with a trial and then subscribe at the end of the trial period.

From a backend perspective, if an end-user’s QuickBooks Online company’s subscription status is “trial” or “subscribed,” your app can use read and write operations.

Users may stop their subscription for various reasons. We may also pause (i.e. restrict or suspend) their subscription due to payment issues. Subscriptions can also expire due to inactivity.

If your end-users’ subscription status is “canceled,” “expired,” “suspended,” or “restricted,” your app is limited to read-only operations.

Users can resubscribe to QuickBooks within certain time frames. If this time elapses, we delete their company data.

qbo/docs/develop/troubleshooting/QBOSubStatus4.png
Check an end-users’ subscription status

Query the CompanyInfo entity using the minorversion=3 parameter.

Check the SubscriptionStatus attribute to see an end-user’s current subscription status.

Tip: Before users QuickBooks Online company files get deleted following a cancellation, expiration, or suspension, disconnect their connection to your app. Learn more about revoking access via OAuth 2.0.

Here are the possible subscription statuses for the CompanyInfo.SubscriptionStatus attribute:

SubscriptionStatus Available operations Description
TRIAL Read/write

The user has a trial version of QuickBooks Online. They have an active, working QuickBooks Online company file.

At the end of their 30 day trial, users can subscribe to QuickBooks Online. If they don’t subscribe, the status changes to “expired.”
TRIALOPTIN Read/write The user has a trial version of QuickBooks Online, and they’ve already paid to start their subscription once their trial ends.
EXPIRED Read only

The user’s trial period is over. Unfortunately, they decided not to subscribe to QuickBooks Online.

Operations other than read display a Validation Fault with error code 6190.

After 90 days, if the user still doesn’t subscribe, we’ll delete their QuickBooks Online company data.

SUBSCRIBED Read/write The user is fully subscribed to QuickBooks Online.
RESTRICTED Read/write

The user is subscribed to QuickBooks Online, but a recent payment wasn’t processed.

If the user doesn’t update their payment info within the next 15 days (US) or 7 days (non-US) from the first day of the “restricted” status, the status changes to “suspended.”
SUSPENDED Read only

The user was subscribed and the “restricted” period time elapsed. The user still hasn’t paid for their subscription.

Operations other than read display a Validation Fault with error code 6190.
CANCELLED Read only

The user canceled their trial or subscription, or it was canceled by our support staff.

Canceled trials remain in the “canceled” status for 90 days.

Canceled subscriptions remain in “canceled” status for 390 days.

If the user doesn’t subscribe to QuickBooks Online after this, we’ll delete their QuickBooks Online company data.

After this, all operations result in a Validation Fault with error code=7001.

UNKNOWN N/A Context of the company is not available.

Note

Note: If you see Error 6190 “Invalid Company Status Error,” it means the subscription period has ended or canceled, or there was a billing problem.