Standardizing Shopify shop data when plan name is unavailable (4xx edge cases)

Shopify Apps
,

Topic summary

An app team is standardizing Shopify shop data but, in edge cases, cannot retrieve the shop’s plan name from the Admin API due to 4xx errors. Plan name is their primary signal for classifying shops.

Observed HTTP responses blocking plan retrieval:

  • 401 Unauthorized (invalid API key or access token)
  • 402 Payment Required (unavailable shop)
  • 403 Forbidden (unavailable shop)
  • 404 Not Found
  • 423 Locked/unknown (store unavailable)

Without the plan name, they cannot reliably classify states, such as:

  • cancelled/closed, frozen/locked, fraudulent, uninstalled app, billing-blocked, paused, etc.

They seek guidance on three points:

  • Whether it is acceptable to infer shop state from these 4xx status codes.
  • Whether there is an official/recommended mapping between specific 4xx codes and shop states (cancelled, frozen, fraudulent, paused, etc.).
  • Whether any documentation links Shopify plan names to these API error responses.

Outcome: No answers provided yet; the thread is requesting official references and remains open.

Summarized with AI on December 26. AI used: gpt-5.
1

We are currently standardizing shop data across many Shopify stores. In normal cases, we rely on the Shopify plan name to classify shops.
However, in several edge cases (cancelled, frozen, fraudulent, etc.), we are unable to retrieve the plan name, as the Admin API returns 4xx errors instead.

Examples of errors we observe:

  • 401 Unauthorized – Invalid API key or access token

  • 402 Payment Required – Unavailable Shop

  • 403 Forbidden – Unavailable Shop

  • 404 Not Found – Not Found

  • 423 Locked / unknown – This store is unavailable

Because of this, we cannot directly determine whether a shop is:

  • cancelled / closed

  • frozen / locked

  • flagged as fraudulent

  • uninstalled the app

  • blocked due to billing issues

  • …

Questions:

  1. When the Shopify plan name cannot be retrieved, is it acceptable to infer shop state based on HTTP status codes (4xx)?

  2. Is there an official or recommended mapping between these status codes and shop states such as:

    • cancelled

    • frozen

    • fraudulent

    • paused

    • …

  3. Is there a documented list of shopify plan name corresponding to these API error responses?

Our goal is to normalize data consistently while handling these exceptional states correctly.

Any guidance or official references would be very helpful.
Thank you.