Ranksy API

Changelog

New endpoints, fields, and behaviour changes in the Ranksy API v1, newest first, each tagged with the semantic version it shipped as. The API is additive — existing endpoints and fields are never removed or renamed — so releases only ever bump the minor or patch number, never the major; v1.0.0 was the initial launch. The version shown here matches the OpenAPI info.version served with that release.

Want to track changes programmatically? Every response is described by the machine-readable OpenAPI spec; diff it between deploys to detect new endpoints and fields.

v1.7.1 — 2026-09-16 — Expired App Events tokens are rejected up front

POST /apps/{app}/track now checks the exp claim of a supplied app_events_token before it records or forwards anything. An already-expired token returns 422 app_events_token_expired instead of being queued and then rejected asynchronously by Shopify with a 401 Token has expired.

A rejected call writes no event row and queues nothing, so refresh the token and resend. Calls with no token, a non-JWT token, or a not-yet-expired token are unchanged. See Track events.

v1.7.0 — 2026-09-03 — Cursor pagination for bulk exports

Additive hardening of the customer and install list endpoints for exporting full datasets into a warehouse. No existing field or endpoint changed.

  • Cursor pagination on GET /apps/{app}/customers, /apps/{app}/store-installs, /apps/{app}/lifecycle-events, /apps/{app}/churned-customers, and /apps/{app}/ltv/customers. Pass cursor instead of page to walk the list by opaque keyset; the response returns next_cursor (and reports page/total_count as null). Cursor mode stays stable while rows are inserted mid-export and isn't subject to the page-mode row cap — use it to pull a full dataset.
  • status=all on GET /apps/{app}/store-installs — return every store regardless of install status (the default stays INSTALLED).
  • subscription_id added to GET /apps/{app}/lifecycle-events rows — the Ranksy subscription the shop held at the event, or null for free-plan / pre-subscription events.
  • New reference pages: Store installs, Lifecycle events, Churned customers, and Customer LTV.

v1.6.0 — 2026-08-30 — Customer notes

Attach free-text notes to a customer — the write side of the CRM, alongside customer tags. Notes support Markdown and an optional reminder.

  • GET /apps/{app}/customers/{installation}/notes — list a customer's notes, newest first (crm:read).
  • POST /apps/{app}/customers/{installation}/notes — create a note (crm:write).
  • PUT /apps/{app}/customers/{installation}/notes/{note} — update a note (crm:write).
  • DELETE /apps/{app}/customers/{installation}/notes/{note} — delete a note (crm:write).

See Notes for fields and examples.

v1.5.0 — 2026-08-29 — Analytics & catalog parity

A large additive batch bringing the API to parity with the Ranksy MCP server, so agents and the ranksy CLI can read everything the assistant can. No existing endpoint changed.

Traffic & installs (traffic:read)

  • GET /apps/{app}/traffic/overview — daily traffic series (page views, installs, CVR).
  • GET /apps/{app}/traffic/attribution — install attribution by channel and model.
  • GET /apps/{app}/traffic/funnel — conversion funnel with revenue-per-customer.
  • GET /apps/{app}/traffic/source-trends — traffic source trends over time.

Keyword analytics (traffic:read)

  • GET /apps/{app}/keywords/cannibalization — organic/ad keyword cannibalization.
  • GET /apps/{app}/keywords/ad-performance — paid keyword ad performance.
  • GET /apps/{app}/keywords/installs-by-source — installs attributed to each keyword.
  • GET /apps/{app}/keywords/{keyword}/trends — daily organic/sponsored trend for one keyword.

Rankings (rankings:read)

  • GET /apps/{app}/rankings/by-keyword/{keyword} — scraped rank rows for a single keyword.

Revenue & customer lifecycle (metrics:read)

  • GET /apps/{app}/revenue/overview — revenue overview snapshot.
  • GET /apps/{app}/churn — churn analysis.
  • GET /apps/{app}/retention/cohorts — customer retention cohorts.
  • GET /apps/{app}/uninstall-reasons — uninstall reason breakdown.
  • GET /apps/{app}/active-trials — active free trials.
  • GET /apps/{app}/churned-customers — churned customers.
  • GET /apps/{app}/ltv/customers and GET /apps/{app}/ltv/cohorts — lifetime value per customer and per acquisition cohort.
  • GET /apps/{app}/store-installs — individual store install records.
  • GET /apps/{app}/lifecycle-events — customer lifecycle event stream.

CRM

  • Customer tag read and write endpoints for segmenting merchants.

App Store catalog (public, no key required)

  • GET /catalog/search — search the App Store catalog.
  • GET /catalog/apps/{slug}, /catalog/apps/{slug}/rankings, /catalog/apps/{slug}/similar, /catalog/apps/{slug}/reviews — per-app catalog data.
  • GET /catalog/categories, /catalog/categories/{handle}/insights, /catalog/categories/{handle}/reviews — category stats and insights.
  • GET /catalog/movers, /catalog/updates — top movers and recent listing updates.
  • GET /catalog/keywords/{keyword}/apps — apps ranking for a keyword.
  • GET /catalog/guidelines — Shopify App Store listing guidelines.

Composite endpoints backed by the Shopify Partner API or BigQuery return 409 when that integration isn't connected; addressing a single resource that isn't tracked returns 404 resource_not_found.

v1.4.0 — 2026-08-28 — Listing, keyword management & account

  • GET /me — the account (team) behind the current API key.
  • GET /apps/{app}/listing — the app's current store listing.
  • POST /apps/{app}/listing/improve plus its read endpoint — request and fetch listing-copy improvements.
  • POST /apps/{app}/keywords and DELETE /apps/{app}/keywords/{keyword} — track and untrack keywords.
  • GET /apps/{app}/rankings now accepts a keyword filter to narrow the response to one keyword.
  • CRM: a merchant's other apps on the same team are now surfaced on the customer profile.
  • Fixes: rate limits are now scoped per app; error responses carry correct doc_urls; not-found and quota errors render through the standard error envelope.

v1.3.0 — 2026-08-24 — Traffic journey

  • GET /apps/{app}/traffic/journey — the install journey / path-to-install breakdown.

v1.2.0 — 2026-08-20 — Conversion signals (Meta CAPI)

  • /identify now stitches ad-click identifiers (fbc) from device signals and reports install conversions in near-real-time, with richer match keys forwarded to the Conversions API.

v1.1.0 — 2026-08-17 — Uninstall reasons on the customer profile

  • The v1 customer profile now includes the merchant's uninstall reason when one was captured.

Was this page helpful?