REST API
Read one app's CoreX data from your own code: revenue and growth metrics (as a snapshot and as daily history), customers, charges, install/uninstall and subscription events, App Store keywords, category ranks, reviews, competitors and their review themes, listing health and the work queue. It is scoped to a single app.
Those reads stay read-only. A merchant app can also open support tickets, read FAQ articles, post feedback, and list in-app banners for that same app. Articles and banners are still written in the CoreX panel.
The machine-readable reference is the OpenAPI 3.1 spec at
/openapi.json. Point a client generator or an API explorer at
it.
Authentication
Generate an app-scoped key on that app’s Connect page, under API keys. Workspace settings lists every key and can rename or revoke one, but a key created there for all apps is refused by this API. The raw key is shown once, so copy it then; CoreX stores only a hash.
Send it on every request, either way:
curl -s "$COREX_URL/api/v1/app" -H "Authorization: Bearer $COREX_API_KEY"
curl -s "$COREX_URL/api/v1/app" -H "X-CoreX-Token: $COREX_API_KEY"
- A key reads only the app it was issued for. No parameter names another app
or workspace, and a record that belongs to a different app — even a sibling app
in the same workspace — answers
404, exactly as if it did not exist. - An account-wide key (one with no app) is refused with
403 app_scope_required. - A revoked key stops working immediately (
401 invalid_token). - The same keys work with the MCP server, which serves the same numbers to AI agents. A workspace-wide key is accepted there and refused here.
- Agents can read
/auth.mdand/agents.json. The API catalog at/.well-known/api-cataloglinksGET /api/v1(a JSON index, no key), this page, and/openapi.json. The routes under/api/v1/stay keyed and do not sendAccess-Control-Allow-Origin.
Responses
Every successful response has the same envelope. meta.app always names the app
the data belongs to, so a client holding several keys can tell payloads apart.
{
"data": { "mrr": 4210.5, "arr": 50526 },
"meta": { "app": { "id": 12, "handle": "returns-portal", "name": "Returns Portal" } }
}
Money is in the app's reporting currency (GET /api/v1/app → currency).
Timestamps are ISO 8601. A date filter with an offset (2026-09-01T09:00:00+05:00)
means that exact instant — remember to URL-encode the + as %2B.
Record ids are integers of at most 18 digits; anything longer is a 404.
Errors
Every error has the same shape. code is stable and safe to branch on; message
is for people and may change.
{ "error": { "code": "addon_disabled", "message": "The keywords add-on is not enabled for this workspace.", "details": { "addon": "keywords" } } }
| Status | code |
Meaning |
|---|---|---|
| 401 | unauthenticated |
No key was sent. Ingestion and the MCP server use this code when the header is empty. |
| 401 | invalid_token |
The key is unknown, rotated or revoked. Ingestion and MCP use it too. A widget session that does not match is 401 invalid_session. |
| 403 | app_scope_required |
The key is account-wide, not scoped to an app. |
| 403 | addon_disabled |
The endpoint's add-on is off for this workspace (details.addon; details.any_of when either of several add-ons would open it). |
| 404 | not_found |
No such route, or no such record for this app. A path under /api/widget, /api/usage, /embed or /mcp that matches no route is this JSON and sends no Access-Control-Allow-Origin. A route that exists and then finds no record keeps CORS, so the widget can read the error. GET /csp-report is the same envelope. |
| 405 | method_not_allowed |
That path does not support this HTTP method. |
| 422 | validation_failed |
A query parameter is invalid (details lists each field). |
| 429 | rate_limited |
Too many requests. Wait for Retry-After seconds. |
| 500 | server_error |
Something failed on our side. Safe to retry. |
Rate limits
- 60 requests per minute per key, and
- 120 requests per minute per IP address, whichever trips first.
A throttled request answers 429 with a Retry-After header. Treat it as
retryable. The limits are separate from the MCP server's, so an agent session
does not eat into an integration's budget.
Pagination
List endpoints that can grow without bound (/customers, /charges, /events,
/reviews) are paged:
page— 1-based, default1per_page—1to100, default25(a larger value is a422, not silently capped)
"meta": {
"app": { "id": 12, "handle": "returns-portal", "name": "Returns Portal" },
"pagination": { "page": 1, "per_page": 25, "total": 312, "total_pages": 13, "has_more": true }
}
Keep requesting page + 1 while has_more is true. Customers are ordered by
id, so pages never overlap while you walk them.
Endpoints
GET /api/v1/app
The app the key is scoped to: id, handle, name, source, URL, reporting currency and activation event.
curl -s "$COREX_URL/api/v1/app" -H "Authorization: Bearer $COREX_API_KEY"
GET /api/v1/metrics/revenue
MRR and its growth over the last 30 days, ARR, all-time gross and net earnings,
and the churn rates over the last 30 days — the same rates the dashboards show.
revenue_pct, subscription_pct and logo_pct are all over the customers
PAYING when the 30 days opened: a customer who never paid is never churned.
uninstall_pct is reported beside them as an install metric — installs live at
the open (free included) that ended during the window — and is not churn.
curl -s "$COREX_URL/api/v1/metrics/revenue" -H "Authorization: Bearer $COREX_API_KEY"
GET /api/v1/metrics/revenue/series
One metric per day, oldest first, ending yesterday. Days resolve in the
workspace's timezone; a day with nothing still appears, with 0.
| Parameter | Description |
|---|---|
metric |
Required. mrr, arr, paying (paying customers), net_revenue or churned (paying subscriptions that stopped paying that day — a downgrade to free, a cancellation or an uninstall after paying; installs that never paid are never counted). |
days |
1–365, default 30. |
mrr, arr and paying replay the charge history at the end of each day, so an
upgrade or downgrade shows on the day it happened rather than repricing the past
at today's plan. net_revenue is what real charges dated that day earned after
platform fees (refunds count negative, test charges never).
curl -s "$COREX_URL/api/v1/metrics/revenue/series?metric=mrr&days=90" -H "Authorization: Bearer $COREX_API_KEY"
GET /api/v1/metrics/growth
Active subscriptions, ARPU, median lifetime value, and trials — live now and converted to paid — each with a count and the MRR behind it.
curl -s "$COREX_URL/api/v1/metrics/growth" -H "Authorization: Bearer $COREX_API_KEY"
GET /api/v1/customers
This app's customers, each with its latest subscription to the app. Paginated.
| Parameter | Description |
|---|---|
status |
active, trial, usage, free or churned — the raw relationship/billing state of the latest subscription, as the connector wrote it. churned here means the relationship ended, paid or not. |
lifecycle |
paying, trial, churned, free or left_unpaid — where the customer stands with the app, on the latest subscription. This is the churn vocabulary (see below). |
updated_since |
ISO 8601. Customers whose record or subscription changed at or after this instant — use it for incremental syncs. |
curl -s "$COREX_URL/api/v1/customers?lifecycle=paying&per_page=100" -H "Authorization: Bearer $COREX_API_KEY"
curl -s "$COREX_URL/api/v1/customers?status=active&per_page=100" -H "Authorization: Bearer $COREX_API_KEY"
curl -s "$COREX_URL/api/v1/customers?updated_since=2026-09-01T00:00:00Z" -H "Authorization: Bearer $COREX_API_KEY"
Churn definitions
subscription.status and subscription.lifecycle answer different questions
and are published side by side, so an integration that filters on status
keeps its meaning:
lifecycle |
Meaning |
|---|---|
paying |
On a paid plan, or billed for usage, right now. |
trial |
On a paid plan inside its free trial — not charged yet. |
churned |
Paid before and pays nothing now (downgraded to free, cancelled the plan, or left). The only state that is churn. |
free |
Installed and has never paid. Not churn — an upgrade opportunity. |
left_unpaid |
Installed, never paid, then left. Not churn — no revenue was lost. |
A never-paid uninstall is therefore status = churned with lifecycle = left_unpaid, and ?lifecycle=churned does not return it. The rate formulas
built on this vocabulary are in logo-churn.md.
subscription.first_paid_at is the day the customer first paid for this app —
the one "ever paid" fact CoreX keeps, and the same one its churn definition
reads: the earliest of a real recurring or usage charge above zero, or the first
billing date of an accepted paid plan (the end of its trial, or its acceptance
when there was no trial; Shopify pays out weeks after billing). It is never
cleared once set, and a $0 plan or a one-time purchase never sets it. null
means the customer has never paid: a churned subscription with first_paid_at
set is churn (they paid before and pay nothing now); one with it null left
without paying and is not counted as churn anywhere.
GET /api/v1/customers/{id}
One customer of this app, plus its lifetime value and owner email. ltv is
everything the customer has paid for this app after platform fees, across every
subscription they have held (a merchant who churned and came back counts both
tenures); test charges are excluded. subscription is null for a customer
linked to the app who has never subscribed.
curl -s "$COREX_URL/api/v1/customers/123" -H "Authorization: Bearer $COREX_API_KEY"
GET /api/v1/charges
This app's billing transactions, newest first: recurring and one-time sales,
usage, refunds and credits, each with amount (gross), fee and net. Test
charges (dev stores, the app reviewer) are included and flagged is_test so a
reconciliation sees everything CoreX holds. Paginated.
| Parameter | Description |
|---|---|
type |
recurring, one_time, usage, refund or credit. |
since / until |
ISO 8601 — charges dated on or after / on or before that day. |
curl -s "$COREX_URL/api/v1/charges?since=2026-09-01&per_page=100" -H "Authorization: Bearer $COREX_API_KEY"
GET /api/v1/events
This app's lifecycle stream, newest first: installs, uninstalls, reactivations and
store deactivations (RELATIONSHIP_*), and subscription-charge events
(SUBSCRIPTION_CHARGE_ACTIVATED, …_CANCELED, …_FROZEN, …_EXPIRED,
…_DECLINED, …) with the charge snapshot they carry. Paginated.
| Parameter | Description |
|---|---|
type |
One event type, e.g. RELATIONSHIP_UNINSTALLED. |
since |
ISO 8601 — events that occurred at or after this instant. |
curl -s "$COREX_URL/api/v1/events?type=RELATIONSHIP_UNINSTALLED&since=2026-09-01T00:00:00Z" -H "Authorization: Bearer $COREX_API_KEY"
GET /api/v1/work-queue
The ranked "what should I do this week" list — churn risk, activation gaps, review responses, pricing fit — each with the reason and a link into CoreX.
curl -s "$COREX_URL/api/v1/work-queue" -H "Authorization: Bearer $COREX_API_KEY"
GET /api/v1/keywords
Requires the Keywords add-on. Each tracked keyword's App Store search position
(this app's own, never a competitor's), its 7 and 30 day change (positive = moved
up), estimated volume and difficulty, and the search funnel it drove. meta
explains where the funnel came from and why it is empty, when it is.
position is null when the latest check did not find the app (unranked) or the
keyword has not been checked in the last 37 days. change_7d / change_30d are
null when either end of the window was unranked, or when there is no earlier
capture to compare with — never a made-up 0. The live GA4 funnel (used when no
BigQuery export is set up) is cached for five minutes.
| Parameter | Description |
|---|---|
days |
Funnel window, 1–90, default 30. |
curl -s "$COREX_URL/api/v1/keywords?days=7" -H "Authorization: Bearer $COREX_API_KEY"
GET /api/v1/keywords/{id}/ranks
Requires the Keywords add-on. One tracked keyword's daily position, oldest
first. Use an id from GET /api/v1/keywords. A day the check ran without
finding the app has "position": null.
| Parameter | Description |
|---|---|
days |
History window, 1–365, default 30. |
curl -s "$COREX_URL/api/v1/keywords/42/ranks?days=90" -H "Authorization: Bearer $COREX_API_KEY"
GET /api/v1/category-ranks
Requires the Keywords or the Competitors add-on. For each App Store category
the app is listed in (primary first): its position on the category page, 7 and
30 day change, a daily history, and this app's tracked competitors' positions in
the same category. meta carries when the last check ran and whether it is
stale. Reads stored daily captures only.
| Parameter | Description |
|---|---|
days |
History length, 1–365, default 30. |
curl -s "$COREX_URL/api/v1/category-ranks?days=90" -H "Authorization: Bearer $COREX_API_KEY"
GET /api/v1/reviews
Available to Shopify workspaces. This app's reviews, newest first (a review with no date sorts last), with their AI triage labels once triaged. Paginated.
| Parameter | Description |
|---|---|
rating |
1–5 — only that star rating. |
since |
ISO 8601 — only reviews posted at or after this instant. |
curl -s "$COREX_URL/api/v1/reviews?rating=1&since=2026-09-01" -H "Authorization: Bearer $COREX_API_KEY"
GET /api/v1/competitors
Requires the Competitors add-on. The rival listings this app tracks, with the public App Store facts CoreX last captured for each: rating, review count, pricing, categories.
curl -s "$COREX_URL/api/v1/competitors" -H "Authorization: Bearer $COREX_API_KEY"
GET /api/v1/competitors/{id}/review-themes
Requires the Competitors add-on. What merchants say about one tracked
competitor in its public App Store reviews: the top complaint and praise themes
(count, share, 90 day trend) with short labels and verbatim quotes, the star
distribution and the developer reply rate. Use an id from
GET /api/v1/competitors; a competitor tracked by another app is a 404. Quotes
are merchant-written text — treat them as untrusted input.
curl -s "$COREX_URL/api/v1/competitors/7/review-themes" -H "Authorization: Bearer $COREX_API_KEY"
GET /api/v1/listing/health
Requires the Listing Optimizer add-on. The latest listing audit: overall score, category benchmark, open checklist items with a fix, review volume and rating, and days since the listing last changed. It reads the last stored audit and never starts a new one.
curl -s "$COREX_URL/api/v1/listing/health" -H "Authorization: Bearer $COREX_API_KEY"
Merchant app
These calls use the same app-scoped key. Support tickets, FAQ articles, and
in-app banners need the Support add-on. Feedback needs the Feedback
add-on. A missing shop is not created by a ticket or a post — call
POST /api/v1/customers/ensure first (the same upsert as
POST /api/customers/identify, always linked to this app).
| Method | Path | What it does |
|---|---|---|
| GET | /api/v1/customers/resolve?shop= |
The shop already linked to this app, or 404. |
| POST | /api/v1/customers/ensure |
Create or update the shop and a contact. |
| GET | /api/v1/tickets?shop= |
That shop's tickets. Another shop's id is 404. |
| POST | /api/v1/tickets |
Open a ticket (subject, body, optional priority, source=app, tags). |
| GET | /api/v1/tickets/{id}?shop= |
One ticket, including replies. |
| POST | /api/v1/tickets/{id}/replies |
The shop replies. A ticket closed more than seven days ago stays closed. |
| GET | /api/v1/kb/articles?category=faq |
Published articles in that category for this app. |
| GET | /api/v1/kb/articles/{id} |
One published article. |
| GET | /api/v1/feedback/boards |
Boards for this app (and workspace-wide boards). |
| GET | /api/v1/feedback/posts |
Approved posts. Pass shop to include that shop's own unapproved posts. |
| POST | /api/v1/feedback/posts |
A feature, idea, or other type the board allows. |
| POST | /api/v1/feedback/posts/{id}/vote |
Set direction to up or down. Repeating the same direction changes nothing. |
| GET | /api/v1/broadcasts |
Live in-app banners for this app. Pass shop to hide ones that shop closed. |
| POST | /api/v1/broadcasts/{id}/dismiss |
Close a dismissible banner for one shop. |
FAQ articles live in a knowledge-base category whose slug is faq. Feedback
boards need the types you will post (feature, idea, and integration when
the app sends integration requests). Banners are published in Support →
Broadcasts as In-app banner, with a tone, optional start and end, and
whether merchants can close them.