> ## 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 hosting API reference
> Authenticated project endpoints, strict request contracts, asynchronous operations, status values, and stable Shopify error codes.
**Live with caveats.** This area is real and usable, but the docs intentionally call out operational or UX limits that still matter.
## Goal
Automate Shopify hosting through the same guarded project service used by the dashboard.
## Prerequisites
* An authenticated StackShift session
* Access to the target project
* An active subscription
## Workflow
Create or read the project’s Shopify connection.
Save target configuration and credentials with PUT requests.
Queue connect and verification work and poll their operation IDs until succeeded or failed.
Read releases, webhook observations, analytics, or submit guarded retries and promotions.
## Authentication, authorization, and envelopes
* Every route is under an authenticated project context and requires an active, non-paused subscription.
* Reads require project access; writes require project mutation permission. An inaccessible project is concealed as not found by the project context.
* Success responses use the standard StackShift envelope with `success`, `status`, `status_code`, `message`, and `data`.
* JSON bodies are limited to 64 KiB, reject unknown fields, and must contain exactly one JSON value.
* Connect and verification return HTTP 202 operations. Supply `Idempotency-Key` to control replay identity; reusing a key with different input returns a conflict.
* Connect accepts optional `settings`, but only the documented storefront/settings keys are valid and credential-shaped keys are always rejected.
## Endpoints
```text theme={null}
GET /api/v1/projects/{projectID}/shopify
POST /api/v1/projects/{projectID}/shopify/connect
GET /api/v1/projects/{projectID}/shopify/operations/{operationID}
PUT /api/v1/projects/{projectID}/shopify/environments/{development|production|preview}
POST /api/v1/projects/{projectID}/shopify/environments/{environment}/verify
GET /api/v1/projects/{projectID}/shopify/releases
POST /api/v1/projects/{projectID}/shopify/releases/{releaseID}/retry
GET /api/v1/projects/{projectID}/shopify/webhooks
GET /api/v1/projects/{projectID}/shopify/webhooks/{webhookID}
PUT /api/v1/projects/{projectID}/shopify/storefront/settings
GET /api/v1/projects/{projectID}/shopify/storefront/analytics?range={range}
POST /api/v1/projects/{projectID}/shopify/storefront/promotions
```
## Core request bodies
```json Connect app theme={null}
{
"kind": "app",
"store_domain": "example.myshopify.com",
"development_branch": "develop"
}
```
```json Connect storefront theme={null}
{
"kind": "storefront",
"store_domain": "example.myshopify.com",
"confirm_generic_storefront": false
}
```
```json App environment theme={null}
{
"config_path": "shopify.app.production.toml",
"config_name": "production",
"app_url": "https://app.example.com",
"client_id": "...",
"client_secret": "...",
"automation_token": "...",
"scopes": "read_products,write_products"
}
```
```json Storefront environment theme={null}
{
"app_url": "https://shop.example.com",
"public_storefront_token": "...",
"private_storefront_token": "...",
"storefront_id": "...",
"customer_account_client_id": "...",
"customer_account_secret": "...",
"customer_account_url": "https://customer-account.example.com"
}
```
```json Promote preview theme={null}
{
"preview_id": "00000000-0000-0000-0000-000000000000"
}
```
## States and secret semantics
* Connection/verification: `pending`, `ready`, `invalid`, or `disabled`. Operation: `queued`, `running`, `succeeded`, or `failed`.
* Release: `queued`, `running`, `healthy`, `failed`, `degraded`, or `cancelled`.
* Stored secrets are write-only. Environment responses expose only `has_client_secret`, `has_automation_token`, `has_public_storefront_token`, `has_private_storefront_token`, `has_customer_account_secret`, and `has_session_secret`.
* Omit or send an empty replacement secret to keep the existing stored value. There is no secret-read endpoint.
* A queued verification is bound to the environment update timestamp and fails if credentials change before execution.
## Analytics range values
* Use `1h`, `24h`, `7d`, or `30d`. An omitted or unrecognized range currently falls back to seven days.
* One-hour data uses minute buckets, 24-hour data uses hour buckets, and 30-day data uses day buckets. Seven-day/default summaries use day buckets while the timeseries uses hour buckets.
## Stable Shopify error codes
* `SHOPIFY_DISABLED` and `SHOPIFY_NOT_FOUND`: HTTP 404.
* `SHOPIFY_INVALID_CONFIGURATION`, `SHOPIFY_INVALID_CREDENTIALS`, `SHOPIFY_CONFIG_MISMATCH`, `SHOPIFY_INCOMPATIBLE_DATABASE`, and `SHOPIFY_UNSUPPORTED_HYDROGEN_RUNTIME`: HTTP 422.
* `SHOPIFY_FAILED_HEALTH_GATE` and `SHOPIFY_IDEMPOTENCY_CONFLICT`: HTTP 409.
* `SHOPIFY_RATE_LIMITED`: HTTP 503. `SHOPIFY_OPERATION_FAILED`: HTTP 500.
* Asynchronous operation failures also persist an `error_code` and redacted `error_message` on the operation object.
## Expected result
API clients can safely repeat durable mutations, never receive stored secret values, and branch on stable Shopify error codes.
## Common failures
* Using an app-only field on a storefront or vice versa
* Sending preview as an app environment
* Malformed UUID or non-HTTPS origin
* Reusing an idempotency key for a different request
* Assuming HTTP 202 means the durable operation has completed
## Related guides
What StackShift hosts, what remains in Shopify, who supplies credentials, and how app and storefront hosting differ.
Prepare supported app source, separate Shopify app targets, committed TOML files, credentials, managed databases, and verification.
Connect Hydrogen or a confirmed Node storefront, obtain Storefront API credentials, isolate targets, and verify Shopify access.