Subscriptions

A single endpoint returns the app's Partner-API subscription entities as a paginated object: "list" — GET /api/v1/apps/:app/subscriptions. Each row is one subscription (plan, status, amount, billing interval) with a stable id for MERGE / dedup, and carries its own ISO currency.

Like every Partner-backed endpoint, this reads the app's Shopify Partner integration. If it is not connected, rejected, or still initializing, expect a 409 — see Errors and the Errors reference. When the integration is connected but the app has no rows yet, you get an empty list, never an error.

GET/api/v1/apps/:app/subscriptions

Subscriptions

The app's Partner-API subscription entities — the row-level detail behind the active_subscriptions count metric. Each row has a stable id for MERGE / dedup and its own ISO currency (the Partner payout currency can differ per subscription, so there is no envelope-level currency). Test subscriptions are excluded by default — pass include_test=true to include them.

Path parameter

Name
app
Type
string
Description
The team app's ULID.

Query parameters

Name
status
Type
string
Description
Filter by status: active, cancelled, declined, expired, frozen.
Name
include_test
Type
boolean
Description
Include Shopify test subscriptions. Default false.
Name
sort
Type
string
Description
Sort column: activated_at (default), cancelled_at, created_at, amount.
Name
order
Type
string
Description
asc or desc (default desc).
Name
page
Type
integer
Description
Page to return. Default 1.
Name
per_page
Type
integer
Description
Rows per page. Default 50, maximum 100.

Request

GET

/api/v1/apps/:app/subscriptions

curl -G https://ranksyapp.com/api/v1/apps/01JN4HKQX0000000000000000/subscriptions \
  -H "Authorization: Bearer rk_live_..." \
  -d status=active \
  -d per_page=50

Response

{
  "object": "list",
  "url": "/api/v1/apps/01JN4HKQX0000000000000000/subscriptions",
  "page": 1,
  "per_page": 50,
  "total_count": 640,
  "has_more": true,
  "metadata": {
    "summary": { "total_subscriptions": 640 },
    "filters": {
      "status": "active",
      "include_test": false,
      "sort": "activated_at",
      "order": "desc"
    }
  },
  "data": [
    {
      "id": "48217",
      "shop": "acme-store.myshopify.com",
      "plan": "Pro",
      "status": "active",
      "amount": 19.0,
      "currency": "USD",
      "billing_interval": "EVERY_30_DAYS",
      "activated_at": "2026-01-14T09:32:11+00:00",
      "cancelled_at": null,
      "created_at": "2026-01-14T09:35:00+00:00"
    }
  ]
}

Subscriptions are the rows behind the aggregate active_subscriptions count in the revenue metrics series.

Response shape

The standard object: "list" envelope. This list is not date-windowed in the series sense, so there is no coverage block, and currency sits on each row (per-subscription payout currency) rather than on the envelope.

Name
object
Type
string
Description
Always "list".
Name
url
Type
string
Description
The endpoint path.
Name
page
Type
integer
Description
Current page number.
Name
per_page
Type
integer
Description
Rows per page.
Name
total_count
Type
integer
Description
Total subscriptions across all pages, after filters.
Name
has_more
Type
boolean
Description
Whether further pages exist.
Name
metadata
Type
object
Description
Carries summary.total_subscriptions (the filtered total) and the echoed filters.
Name
data
Type
array
Description
The subscription rows for this page.

Subscription row

Name
id
Type
string
Description
Stable Partner-API subscription id. Use it to MERGE / dedup downstream.
Name
shop
Type
string
Description
The subscribing store's myshopify.com domain.
Name
plan
Type
string
Description
The plan name the shop is on.
Name
status
Type
string
Description
One of active, cancelled, declined, expired, frozen.
Name
amount
Type
number
Description
The subscription amount in currency.
Name
currency
Type
string
Description
ISO code for this subscription's payout currency (can differ per row).
Name
billing_interval
Type
string
Description
Partner billing interval, e.g. EVERY_30_DAYS.
Name
activated_at
Type
string
Description
ISO timestamp when the subscription activated, or null.
Name
cancelled_at
Type
string
Description
ISO timestamp when the subscription cancelled, or null.
Name
created_at
Type
string
Description
ISO timestamp when the row was created.

Pagination

Walk the result set with page and per_page (default 50, maximum 100), and check has_more / total_count to know when to stop. total_count and metadata.summary are computed after your filters, so paging never changes them within a single filtered query.

Errors

Beyond the universal 401 / 403 / 422 / 429 (see Errors), this endpoint returns:

409 — the app's Shopify Partner integration isn't usable: partner_integration_not_connected, partner_integration_unauthorized (reconnect in Ranksy), or partner_integration_pending (first sync still running — retry shortly).

A bad query parameter (unknown status, out-of-range per_page) surfaces as a 422.