​

Merchandising & Content Toolkit API overview

​

Authentication

curl -H "Authorization: Bearer <shopify-session-token>" \
  "${APP_ORIGIN:?Set APP_ORIGIN}/api/collections"

​

Public endpoints

• GET /api/health and GET /healthz — no authentication; return build identity and database/Redis status.
• GET /api/public/market-ranking — App-proxy HMAC market ranking.
• GET /api/public/merchandising/ab-tests/:id/assignment and POST /api/public/merchandising/ab-tests/:id/metrics — storefront A/B assignment and metrics, gated by the experiment token and the Advanced entitlement.
• GET /privacy and GET /terms — HTTP 301 redirects to the shared docs-site policy pages.
• /marketing, /features/*, /pricing, /cookies, /accessibility, /support, /sitemap.xml, /robots.txt — public marketing, pricing, and policy pages.

​

Admin endpoints

​

Collections, products, and pages

• GET /api/collections — list collections with pagination (first, after, query).
• GET /api/collections/search — search collections by title.
• GET /api/collections/:id — get a collection with its products.
• GET /api/products and GET /api/products/search — list and search products.
• GET /api/pages — list pages.

​

Sorting rules and jobs

• GET /api/sorting-rules, POST /api/sorting-rules, GET /api/sorting-rules/:id, PUT /api/sorting-rules/:id, DELETE /api/sorting-rules/:id.
• POST /api/sorting-rules/:id/run — enqueue a background sorting job.
• GET /api/sorting-jobs and GET /api/sorting-jobs/:id — job history and details.

​

Hierarchy and content

• GET /api/hierarchy and POST /api/hierarchy/save — read and update the collection tree.
• GET /api/content/:resourceType/:resourceId and POST /api/content/:resourceType/:resourceId — read and save content blocks, where resourceType is product, collection, or page.

​

Metafield definition maintenance

• GET /api/metafield-definitions — read-only health report.
• POST /api/metafield-definitions/reconcile — repair Shopify/local definition drift.

​

Billing

• GET /api/billing — current plan, entitlements, and domains.
• GET /api/billing/plans — annotated plan list.
• POST /api/billing/select — request a plan via the Billing API (paid plans return a confirmation URL; free cancels any active charge).
• GET /api/billing/confirmed — reconcile after Shopify confirmation.

​

Merchandising (Advanced-gated)

• GET /api/merchandising/ga4 and POST /api/merchandising/ga4 — GA4 integration config (requires ga4Integration).
• POST /api/merchandising/ab-tests — create an A/B experiment.
• POST /api/merchandising/ai-tags/generate and PUT /api/merchandising/ai-tags — generate and persist urgency tags (requires aiSentimentUrgencyTags, Pro+).

​

Advanced tools

• GET /api/analytics — advanced analytics dashboard summary.
• GET /api/dynamic-collections, POST /api/dynamic-collections, POST /api/dynamic-collections/:id/run — dynamic collection rules.
• GET /api/merchant-webhooks and POST /api/merchant-webhooks — signed outbound webhooks (secrets omitted in responses).
• GET /api/privacy-exports and GET /api/privacy-exports/:id/download — list and download customer data exports.

​

Dashboard and setup

• GET /api/dashboard, POST /api/dashboard/skip-setup — home metrics and setup skip.
• GET /api/setup-status, GET /api/setup-status/themes, GET /api/setup-status/themes/:themeId, POST /api/setup-status/skip — onboarding progress and theme choices.

​

Error responses

{
  "error": {
    "message": "Description of the error"
  }
}