> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackshift.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Shopify security and troubleshooting

> Credential storage and isolation guarantees, launch-check interpretation, stable failure codes, and a production diagnosis sequence.

<Warning>
  **Live with caveats.** This area is real and usable, but the docs intentionally call out operational or UX limits that still matter.
</Warning>

## Goal

Diagnose Shopify hosting failures using persisted evidence while preserving tenant and environment isolation.

## Prerequisites

* Project access
* The failed operation or release ID
* Application logs for app-owned OAuth, session, or webhook failures

## Workflow

<Steps>
  <Step>
    Identify whether the failure is connection, target verification, backend deployment, Shopify release, storefront promotion, or ingress observation.
  </Step>

  <Step>
    Read the durable operation/release status, step, stable error code, redacted message, and attempt count.
  </Step>

  <Step>
    Compare target `has_*` flags and verification timestamps with the current committed branch configuration.
  </Step>

  <Step>
    Resolve the specific gate; do not bypass isolation by copying production credentials into development.
  </Step>

  <Step>
    Retry only after the underlying state changed, then re-check launch checks and runtime health.
  </Step>
</Steps>

## Credential guarantees and limits

* Client secrets, automation tokens, private Storefront tokens, Customer Account secrets, and generated session secrets are encrypted at rest with the platform encryption key.
* Public Storefront tokens are stored as non-returning credential data but are not encrypted because they are designed for public clients. They are still omitted from API responses and logs.
* Secret fields reject values over 8 KiB and CR, LF, or NUL bytes. Identifier/scopes fields are limited to 512 characters; URLs are clean HTTPS origins.
* Credentials are decrypted only when building the selected runtime environment or executing a constrained verification/release step.
* StackShift does not store merchant OAuth access tokens, Shopify session tokens, webhook bodies, or webhook HMAC headers for this feature.

## Launch-check interpretation

* A ready connection requires ready development and production credential targets. Storefront preview readiness is not required for connection readiness.
* App launch additionally requires reachable callback/webhook routes, a healthy production backend, a healthy development backend and Shopify release, and supported observed webhook API versions.
* Shop Pay checks appear only when Shop Pay is requested and require production credentials, TLS, checkout confirmation, and component evidence.
* Pending means evidence is not yet available; it must not be treated as passing. Invalid means a concrete check failed and includes a target error message.

## Diagnosis by error code

* `SHOPIFY_INVALID_CREDENTIALS`: confirm token type, target ownership, expiry/rotation, store domain, and whether credentials changed after verification was queued.
* `SHOPIFY_CONFIG_MISMATCH`: compare committed TOML at the target branch with saved config path/name, client ID, and webhook API version.
* `SHOPIFY_INCOMPATIBLE_DATABASE`: confirm the generated/bound database is project-owned PostgreSQL, running, and exposes a connection string.
* `SHOPIFY_UNSUPPORTED_HYDROGEN_RUNTIME`: add a supported Node adapter and start command; Oxygen-only runtime is not deployable here.
* `SHOPIFY_FAILED_HEALTH_GATE`: inspect route status, runtime/deployment health, preview activity/expiry/digest, TLS, or active-release conflicts based on the operation.
* `SHOPIFY_RATE_LIMITED`: keep the operation durable and allow its bounded retry schedule; do not fan out manual retries.

## Escalate immediately

* A release is `degraded`, indicating backend or Shopify compensation could not restore a consistent known state.
* A critical `WEBHOOK_REPEATED_5XX` alert remains open after application recovery.
* A secret appears in a persisted log or API response; revoke/rotate it in Shopify first, then preserve the incident evidence.
* Production and development point to the same app identity, URL, or database despite validation expectations.

## Expected result

<Check>
  The failed layer is identified from durable evidence and restored without exposing credentials or weakening production gates.
</Check>

## Common failures

<Warning>
  * Reading a redacted generic error without opening the associated durable operation/release
  * Retrying before rotating an expired token or fixing committed configuration
  * Treating observed webhooks as proof of HMAC verification
  * Using the platform server environment for tenant credentials
  * Treating a degraded compensated release as healthy
</Warning>

## Related guides

<CardGroup cols={2}>
  <Card title="Shopify hosting overview" href="/shopify/overview">
    What StackShift hosts, what remains in Shopify, who supplies credentials, and how app and storefront hosting differ.
  </Card>

  <Card title="Shopify hosting API reference" href="/shopify/api-reference">
    Authenticated project endpoints, strict request contracts, asynchronous operations, status values, and stable Shopify error codes.
  </Card>

  <Card title="Shopify webhooks and observability" href="/shopify/webhooks-and-observability">
    Application-owned HMAC verification, metadata-only ingress observations, duplicate accounting, retention, alerts, and launch checks.
  </Card>
</CardGroup>