SwiftPage API overview

This page documents SwiftPage’s externally reachable app and storefront endpoints. Operational maintenance interfaces are outside this public reference.

Authentication

Authenticated endpoints require a Shopify App Bridge session token (JWT) in the Authorization header:

Authorization: Bearer <session-token>

SwiftPage validates that the token was issued for the app and that its destination identifies a Shopify shop. That verified destination scopes the authenticated request to the current shop.

Read-only request

The health route needs no authentication, so it is the simplest request to try. Set APP_ORIGIN to your deployed app’s HTTPS origin, without a trailing slash.

curl --fail-with-body "${APP_ORIGIN:?Set APP_ORIGIN}/health"

Public endpoints

Method	Path	Description
`GET`	`/health`	Health check: `{ status, app, timestamp }`
`GET`	`/auth/install?shop={shop}`	Start OAuth; redirects to Shopify authorization
`GET`	`/auth/callback?shop={shop}&code={code}&hmac={hmac}&state={state}`	OAuth callback; verifies HMAC and state, completes authorization, and registers supported webhooks
`POST`	`/webhooks/shopify`	Webhook receiver (HMAC-verified)

Shop and templates

Method	Path	Description
`GET`	`/api/me`	Current shop info: `shop`, `plan`, `entitlements`, `canPublish`, `installedAt`, and `setup` timestamps
`GET`	`/api/templates`	List starter templates (id, name, category, description, layout)
`POST`	`/api/support`	Store an authenticated support request: `email`, `message` (10–5000 chars)
`POST`	`/api/setup/skip`	Record the initial dismissal of the setup modal
`POST`	`/api/setup/confirm-theme`	Record merchant confirmation of the theme block when status is unavailable

Pages

Method	Path	Description
`GET`	`/api/pages`	List pages for the shop
`GET`	`/api/pages/:id`	Get one page, including its layout
`POST`	`/api/pages`	Create a page: `title`, `handle`, optional `seo_title`, `seo_description`, `layout_json`, `template_id`
`PUT`	`/api/pages/:id`	Update a page (all fields optional)
`DELETE`	`/api/pages/:id`	Delete a page; if it is published on Shopify, the Shopify page is deleted first
`POST`	`/api/pages/:id/publish`	Create or update the Shopify Page, synchronize its published content, and save a version
`POST`	`/api/pages/:id/unpublish`	Set the Shopify Page to unpublished
`POST`	`/api/pages/:id/export`	Export the page as a ZIP (Scale or Agency)

Sending X-SwiftPage-One-Click: 1 on publish uses the Growth one-click publish shortcut; without the entitlement it is rejected with 403 plan_limit. Publishing returns 403 when the plan page limit is reached or when the metaobject scopes are missing (reauthorize prompt). CSS dimension fields (width, height, padding, margin, maxWidth) in section settings and mobile overrides are sanitized on update.

Shopify proxy

Method	Path	Description
`GET`	`/api/shopify/products?query={query}`	Search products
`GET`	`/api/shopify/collections?query={query}`	Search collections
`POST`	`/api/shopify/files/image-upload`	Create a staged image upload: `filename`, `mimeType`, `fileSize`
`POST`	`/api/shopify/files/complete`	Register a staged upload as a Shopify file: `resourceUrl`, optional `alt`

When the Growth image-compression setting is enabled, the editor resizes eligible JPEG/PNG/WebP selections before requesting the staged target. GIF and SVG uploads are preserved unchanged.

Billing

Method	Path	Description
`GET`	`/api/billing`	Current plan, published page count, subscription GID, interval, trial eligibility, and plan list
`POST`	`/api/billing/subscribe`	Create an app-managed charge: `planId` (`growth`, `pro`, `scale`, `free`), optional `interval` (`monthly`/`annual`), and a client-stable `idempotencyKey`. Returns Shopify’s `confirmationUrl`
`POST`	`/api/billing/cancel`	Cancel the active subscription

Paid requests require a 16–128 character idempotencyKey; the client reuses the same key when offering a retry. Selecting free cancels the active subscription. Paid entitlements are not granted until Shopify reports an active subscription. Requires the admin collaborator role.

Feature endpoints

Premium capabilities live under /api/features/*. Each route enforces a server-side entitlement for the authenticated shop; calls below the required tier return 403 plan_limit.

Method	Path	Entitlement (min tier)
`POST`	`/api/features/ai/copy`	`aiCopyStarter` (Free)
`POST`	`/api/features/ai/layout`	`aiLayoutGeneration` (Growth)
`POST` / `GET`	`/api/features/reusable-blocks`	`reusableBlocks` (Growth)
`PUT` / `DELETE`	`/api/features/reusable-blocks/:id`	`reusableBlocks` (Growth)
`POST`	`/api/features/theme-sync`	`themeSectionSync` (Growth)
`POST`	`/api/features/seo-audit/:pageId`	`seoAudits` (Pro)
`POST`	`/api/features/experiments`	`abTesting` (Pro)
`POST`	`/api/features/experiments/:id/complete`	`abTesting` (Pro)
`POST`	`/api/features/localizations/:pageId`	`localization` (Pro)
`POST`	`/api/features/content-sync`	`contentSyncing` (Pro)
`POST`	`/api/features/funnels`	`funnelsPostPurchase` (Scale)
`POST`	`/api/features/3d-models/:pageId`	`model3dSupport` (Scale)
`POST`	`/api/features/collaborators`	`collaborationRoles` (Scale)
`POST`	`/api/features/webhooks`	`apiWebhooks` (Scale)
`GET` / `PUT`	`/api/features/shop-settings`	`customFontsCss` (Growth)
`GET` / `POST`	`/api/features/experiments/:id/schedule`	`advancedExperiments` (Scale)
`GET` / `POST`	`/api/features/org`	`multiStore` (Agency)
`GET`	`/api/features/migration/export`	`migration` (Agency)
`POST`	`/api/features/migration/import`	`migration` (Agency)

App Proxy

Method	Path	Description
`POST`	`/apps/swiftpage/track`	Signed App Proxy endpoint that records anonymous `visitor_id`, `page_view`, and `conversion` events for the rolling 90-day analytics surface

Maintenance

Operational repair interfaces are not part of SwiftPage’s public API contract and are intentionally omitted from this reference.

Rate limiting

Authenticated /api/pages routes use a per-shop fixed-window limit of 60 requests per 60 seconds, keyed by shop domain. Responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. Exceeded windows return 429 rate_limited with a Retry-After header.

Errors

All errors use:

{ "error": "error_code", "message": "Human-readable message", "details": [] }

Common codes include bad_request, validation_error, unauthorized, forbidden, rate_limited, plan_limit, not_found, publish_error, billing_error, billing_request_in_progress, billing_request_expired, idempotency_conflict, billing_sync_error, duplicate_handle, delete_error, and server_error. Pcnaid Documentation › Shopify Ecosystem › SwiftPage › Developer

Start here

Documentation hubs

Legal

Shared legal

SwiftPage API overview

SwiftPage API overview

Authentication

Read-only request

Public endpoints

Shop and templates

Pages

Shopify proxy

Billing

Feature endpoints

App Proxy

Maintenance

Rate limiting

Errors

​SwiftPage API overview

​Authentication

​Read-only request

​Public endpoints

​Shop and templates

​Pages

​Shopify proxy

​Billing

​Feature endpoints

​App Proxy

​Maintenance

​Rate limiting

​Errors

SwiftPage API overview

Authentication

Read-only request

Public endpoints

Shop and templates

Pages

Shopify proxy

Billing

Feature endpoints

App Proxy

Maintenance

Rate limiting

Errors