---
title: subscriptions
description: >-
  Reference for the ShopifyQL `subscriptions` table. Every metric and dimension,
  paired with worked example queries.
api_version: 2026-07
source_url:
  html: >-
    https://shopify.dev/docs/api/shopifyql/latest/schemas/sales_revenue/subscriptions
  md: >-
    https://shopify.dev/docs/api/shopifyql/latest/schemas/sales_revenue/subscriptions.md
api_name: shopifyql
---

# subscriptions

The `subscriptions` [schema](https://shopify.dev/docs/api/shopifyql/latest/schemas) captures subscription count snapshots. It's a source for active, added, and canceled subscription movement by interval.

### Use cases

* **Subscription base**: Group [`active_subscriptions`](#subscriptionsmetric-propertydetail-activesubscriptions) by month to show the subscription base over time.
* **Movement**: Compare [`subscriptions_added`](#subscriptionsmetric-propertydetail-subscriptionsadded) and [`subscriptions_canceled`](#subscriptionsmetric-propertydetail-subscriptionscanceled) for the same snapshot interval to see whether the subscription base is growing or churning.

Examples

### Examples

* ####

  ##### Description

  Compare monthly \`active\_subscriptions\` for this year with a year-over-year percent-change column. This example uses \[\`COMPARE TO previous\_year\`]\(/docs/api/shopifyql/latest/syntax/compare-to) to benchmark each month against the same month last year.

  ##### ShopifyQL

  ```shopifyql
  FROM subscriptions
    SHOW active_subscriptions
    TIMESERIES month WITH PERCENT_CHANGE
    DURING this_year
    COMPARE TO previous_year
    ORDER BY month ASC
  VISUALIZE active_subscriptions TYPE line
  ```

* ####

  ##### Description

  Compare \[\`subscriptions\_added\`]\(#subscriptionsmetric-propertydetail-subscriptionsadded) and \`subscriptions\_canceled\` by quarter for the last eight quarters. This example uses a line chart to show subscription additions and cancellations over time.

  ##### ShopifyQL

  ```shopifyql
  FROM subscriptions
    SHOW subscriptions_added, subscriptions_canceled
    TIMESERIES quarter WITH TOTALS
    SINCE startOfQuarter(-7q) UNTIL today
    ORDER BY quarter ASC
  VISUALIZE subscriptions_added, subscriptions_canceled TYPE line
  ```

* ####

  ##### Description

  Break down \`active\_subscriptions\` and \`subscriptions\_canceled\` by \`quarter\` across this year. This example uses \[\`GROUP BY\`]\(/docs/api/shopifyql/latest/syntax/group-by) to compare the active base with cancellations each quarter.

  ##### ShopifyQL

  ```shopifyql
  FROM subscriptions
    SHOW active_subscriptions, subscriptions_canceled
    GROUP BY quarter WITH TOTALS
    DURING this_year
    ORDER BY quarter ASC
  VISUALIZE active_subscriptions TYPE line
  ```

* ####

  ##### Description

  Break down \`active\_subscriptions\` and \`subscriptions\_added\` by \`week\` across last quarter. This example uses \[\`GROUP BY\`]\(/docs/api/shopifyql/latest/syntax/group-by) to compare new additions with the active base each week.

  ##### ShopifyQL

  ```shopifyql
  FROM subscriptions
    SHOW active_subscriptions, subscriptions_added
    GROUP BY week WITH TOTALS
    DURING last_quarter
    ORDER BY week ASC
  VISUALIZE active_subscriptions TYPE line
  ```

***

## Metrics

Counts and calculations that let you track key business indicators. Metrics show up as the columns when queried.

Metrics you can use when querying `FROM subscriptions`.

* **active\_​subscriptions**

  **INTEGER**

  The active subscription count from the latest measurement in each period.

* **subscriptions\_​added**

  **INTEGER**

  Number of subscriptions your customers added in the given period

* **subscriptions\_​canceled**

  **INTEGER**

  Number of subscriptions your customers canceled in the given period

### INTEGER

A whole number without decimal places, used for counts, quantities, and other discrete numeric values.

```ts
```

***

## Dimensions

Attributes of your data that let you look more granularly at aspects of the data. Group and filter by dimensions to shape the rows your query returns.

Dimensions you can use when querying `FROM subscriptions`.

* **day**

  **DAY\_TIMESTAMP**

  The day your subscription summary applies to.

* **month**

  **MONTH\_TIMESTAMP**

  The month your subscription summary applies to.

* **quarter**

  **QUARTER\_TIMESTAMP**

  A three-month calendar quarter, Q1 through Q4.

* **shop\_​id**

  **IDENTITY**

  The unique Shopify identifier for your store. Use [`shop_id`](#subscriptionsdimension-propertydetail-shopid) with [`shop_name`](#subscriptionsdimension-propertydetail-shopname) to show readable store labels.

* **week**

  **WEEK\_TIMESTAMP**

  The week your subscription summary applies to.

* **year**

  **YEAR\_TIMESTAMP**

  The year your subscription summary applies to.

* **shop\_​name**

  **STRING**

  Name of your store

### DAY\_TIMESTAMP

A date value truncated to day precision.

```ts
```

### MONTH\_TIMESTAMP

A date value representing the start of a month.

```ts
```

### QUARTER\_TIMESTAMP

A date value representing the start of a fiscal quarter.

```ts
```

### IDENTITY

A unique identifier for a Shopify resource such as a customer, product, or order.

```ts
```

### WEEK\_TIMESTAMP

A date value representing the start of a week.

```ts
```

### YEAR\_TIMESTAMP

A date value representing the start of a year.

```ts
```

### STRING

A sequence of characters representing text data.

```ts
```

***

## Related schemas

* [`fulfillments`](https://shopify.dev/docs/api/shopifyql/latest/schemas/orders/fulfillments): Fulfillment events when you want to track recurring shipments tied to subscription orders.
* [`sales`](https://shopify.dev/docs/api/shopifyql/latest/schemas/sales_revenue/sales): Sale-level data when you want to attribute revenue back to subscription orders.
* [`customers`](https://shopify.dev/docs/api/shopifyql/latest/schemas/customers/customers): Customer-level data for lifetime value of subscribers and one-off buyers.

***