Shopify hosting API reference

​

Goal

​

Prerequisites

• An authenticated StackShift session
• Access to the target project
• An active subscription

​

Workflow

​

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

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

{
  "kind": "app",
  "store_domain": "example.myshopify.com",
  "development_branch": "develop"
}

{
  "kind": "storefront",
  "store_domain": "example.myshopify.com",
  "confirm_generic_storefront": false
}

{
  "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"
}

{
  "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"
}

{
  "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

​

Common failures

​

Related guides