Subscription Queries

You can fetch subscriptions in your templates or PHP code using subscription queries.

Twig
PHP

{# Create a new subscription query #}
{% set mySubscriptionQuery = craft.subscriptions() %}

Once you’ve created a subscription query, you can set parameters on it to narrow down the results, and then execute it (opens new window) by calling .all(). An array of Subscription (opens new window) objects will be returned.

See Element Queries (opens new window) in the Craft docs to learn about how element queries work.

# Example

We can display all of the current user’s subscriptions by doing the following:

Create a subscription query with craft.subscriptions().
Set the user parameter on it.
Fetch the subscriptions with .all().
Loop through the subscriptions using a for (opens new window) tag to output their HTML.

{# Make sure someone is logged in #}
{% requireLogin %}

{# Create a subscription query with the 'user' parameter #}
{% set mySubscriptionQuery = craft.subscriptions()
  .user(currentUser) %}

{# Fetch the subscriptions #}
{% set subscriptions = mySubscriptionQuery.all() %}

{# Display the subscriptions #}
{% for subscription in subscriptions %}
  <article>
    <h1><a href="{{ subscription.url }}">{{ subscription.title }}</a></h1>
    {{ subscription.summary }}
    <a href="{{ subscription.url }}">Learn more</a>
  </article>
{% endfor %}

# Parameters

Subscription queries support the following parameters:

Param	Description
anyStatus	Clears out the status and enabledForSite() (opens new window) parameters.
asArray	Causes the query to return matching subscriptions as arrays of data, rather than Subscription (opens new window) objects.
clearCachedResult	Clears the cached result.
dateCanceled	Narrows the query results based on the subscriptions’ cancellation date.
dateCreated	Narrows the query results based on the subscriptions’ creation dates.
dateExpired	Narrows the query results based on the subscriptions’ expiration date.
dateSuspended	Narrows the query results based on the subscriptions’ suspension date.
dateUpdated	Narrows the query results based on the subscriptions’ last-updated dates.
fixedOrder	Causes the query results to be returned in the order specified by id.
gatewayId	Narrows the query results based on the gateway, per its ID.
hasStarted	Narrows the query results to only subscriptions that have started.
id	Narrows the query results based on the subscriptions’ IDs.
ignorePlaceholders	Causes the query to return matching subscriptions as they are stored in the database, ignoring matching placeholder elements that were set by craft\services\Elements::setPlaceholderElement() (opens new window).
inReverse	Causes the query results to be returned in reverse order.
isCanceled	Narrows the query results to only subscriptions that are canceled.
isExpired	Narrows the query results to only subscriptions that have expired.
isSuspended	Narrows the query results to only subscriptions that are suspended.
limit	Determines the number of subscriptions that should be returned.
nextPaymentDate	Narrows the query results based on the subscriptions’ next payment dates.
offset	Determines how many subscriptions should be skipped in the results.
onTrial	Narrows the query results to only subscriptions that are on trial.
orderBy	Determines the order that the subscriptions should be returned in. (If empty, defaults to `dateCreated DESC`.)
orderId	Narrows the query results based on the order, per its ID.
plan	Narrows the query results based on the subscription plan.
planId	Narrows the query results based on the subscription plans’ IDs.
preferSites	If unique() (opens new window) is set, this determines which site should be selected when querying multi-site elements.
reference	Narrows the query results based on the reference.
relatedTo	Narrows the query results to only subscriptions that are related to certain other elements.
search	Narrows the query results to only subscriptions that match a search query.
status	Narrows the query results based on the subscriptions’ statuses.
trashed	Narrows the query results to only subscriptions that have been soft-deleted.
trialDays	Narrows the query results based on the number of trial days.
uid	Narrows the query results based on the subscriptions’ UIDs.
user	Narrows the query results based on the subscriptions’ user accounts.
userId	Narrows the query results based on the subscriptions’ user accounts’ IDs.
with	Causes the query to return matching subscriptions eager-loaded with related elements.

# `anyStatus`

Clears out the status and enabledForSite() (opens new window) parameters.

Twig
PHP

{# Fetch all subscriptions, regardless of status #}
{% set subscriptions = craft.subscriptions()
    .anyStatus()
    .all() %}

# `asArray`

Causes the query to return matching subscriptions as arrays of data, rather than Subscription (opens new window) objects.

Twig
PHP

{# Fetch subscriptions as arrays #}
{% set subscriptions = craft.subscriptions()
    .asArray()
    .all() %}

# `clearCachedResult`

Clears the cached result.

# `dateCanceled`

Narrows the query results based on the subscriptions’ cancellation date.

Possible values include:

Value	Fetches subscriptions…
`'>= 2018-04-01'`	that were canceled on or after 2018-04-01.
`'< 2018-05-01'`	that were canceled before 2018-05-01
`['and', '>= 2018-04-04', '< 2018-05-01']`	that were canceled between 2018-04-01 and 2018-05-01.

Twig
PHP

{# Fetch subscriptions that were canceled recently #}
{% set aWeekAgo = date('7 days ago')|atom %}

{% set subscriptions = craft.subscriptions()
    .dateCanceled(">= #{aWeekAgo}")
    .all() %}

# `dateCreated`

Narrows the query results based on the subscriptions’ creation dates.

Possible values include:

Value	Fetches subscriptions…
`'>= 2018-04-01'`	that were created on or after 2018-04-01.
`'< 2018-05-01'`	that were created before 2018-05-01
`['and', '>= 2018-04-04', '< 2018-05-01']`	that were created between 2018-04-01 and 2018-05-01.

Twig
PHP

{# Fetch subscriptions created last month #}
{% set start = date('first day of last month')|atom %}
{% set end = date('first day of this month')|atom %}

{% set subscriptions = craft.subscriptions()
    .dateCreated(['and', ">= #{start}", "< #{end}"])
    .all() %}

# `dateExpired`

Narrows the query results based on the subscriptions’ expiration date.

Possible values include:

Value	Fetches subscriptions…
`'>= 2018-04-01'`	that expired on or after 2018-04-01.
`'< 2018-05-01'`	that expired before 2018-05-01
`['and', '>= 2018-04-04', '< 2018-05-01']`	that expired between 2018-04-01 and 2018-05-01.

Twig
PHP

{# Fetch subscriptions that expired recently #}
{% set aWeekAgo = date('7 days ago')|atom %}

{% set subscriptions = craft.subscriptions()
    .dateExpired(">= #{aWeekAgo}")
    .all() %}

# `dateSuspended`

Narrows the query results based on the subscriptions’ suspension date.

Possible values include:

Value	Fetches subscriptions…
`'>= 2018-04-01'`	that were suspended on or after 2018-04-01.
`'< 2018-05-01'`	that were suspended before 2018-05-01
`['and', '>= 2018-04-04', '< 2018-05-01']`	that were suspended between 2018-04-01 and 2018-05-01.

Twig
PHP

{# Fetch subscriptions that were suspended recently #}
{% set aWeekAgo = date('7 days ago')|atom %}

{% set subscriptions = craft.subscriptions()
    .dateSuspended(">= #{aWeekAgo}")
    .all() %}

# `dateUpdated`

Narrows the query results based on the subscriptions’ last-updated dates.

Possible values include:

Value	Fetches subscriptions…
`'>= 2018-04-01'`	that were updated on or after 2018-04-01.
`'< 2018-05-01'`	that were updated before 2018-05-01
`['and', '>= 2018-04-04', '< 2018-05-01']`	that were updated between 2018-04-01 and 2018-05-01.

Twig
PHP

{# Fetch subscriptions updated in the last week #}
{% set lastWeek = date('1 week ago')|atom %}

{% set subscriptions = craft.subscriptions()
    .dateUpdated(">= #{lastWeek}")
    .all() %}

# `fixedOrder`

Causes the query results to be returned in the order specified by id.

Twig
PHP

{# Fetch subscriptions in a specific order #}
{% set subscriptions = craft.subscriptions()
    .id([1, 2, 3, 4, 5])
    .fixedOrder()
    .all() %}

# `gatewayId`

Narrows the query results based on the gateway, per its ID.

Possible values include:

Value	Fetches subscriptions…
`1`	with a gateway with an ID of 1.
`'not 1'`	not with a gateway with an ID of 1.
`[1, 2]`	with a gateway with an ID of 1 or 2.
`['not', 1, 2]`	not with a gateway with an ID of 1 or 2.

# `hasStarted`

Narrows the query results to only subscriptions that have started.

Twig
PHP

{# Fetch started subscriptions #}
{% set subscriptions = craft.subscriptions()
    .hasStarted()
    .all() %}

# `id`

Narrows the query results based on the subscriptions’ IDs.

Possible values include:

Value	Fetches subscriptions…
`1`	with an ID of 1.
`'not 1'`	not with an ID of 1.
`[1, 2]`	with an ID of 1 or 2.
`['not', 1, 2]`	not with an ID of 1 or 2.

Twig
PHP

{# Fetch the subscription by its ID #}
{% set subscription = craft.subscriptions()
    .id(1)
    .one() %}

This can be combined with fixedOrder if you want the results to be returned in a specific order.

# `ignorePlaceholders`

Causes the query to return matching subscriptions as they are stored in the database, ignoring matching placeholder elements that were set by craft\services\Elements::setPlaceholderElement() (opens new window).

# `inReverse`

Causes the query results to be returned in reverse order.

Twig
PHP

{# Fetch subscriptions in reverse #}
{% set subscriptions = craft.subscriptions()
    .inReverse()
    .all() %}

# `isCanceled`

Narrows the query results to only subscriptions that are canceled.

Twig
PHP

{# Fetch canceled subscriptions #}
{% set subscriptions = craft.subscriptions()
    .isCanceled()
    .all() %}

# `isExpired`

Narrows the query results to only subscriptions that have expired.

Twig
PHP

{# Fetch expired subscriptions #}
{% set subscriptions = craft.subscriptions()
    .isExpired()
    .all() %}

# `isSuspended`

Narrows the query results to only subscriptions that are suspended.

Twig
PHP

{# Fetch suspended subscriptions #}
{% set subscriptions = craft.subscriptions()
    .isSuspended()
    .all() %}

# `limit`

Determines the number of subscriptions that should be returned.

Twig
PHP

{# Fetch up to 10 subscriptions  #}
{% set subscriptions = craft.subscriptions()
    .limit(10)
    .all() %}

# `nextPaymentDate`

Narrows the query results based on the subscriptions’ next payment dates.

Possible values include:

Value	Fetches subscriptions…
`'>= 2018-04-01'`	with a next payment on or after 2018-04-01.
`'< 2018-05-01'`	with a next payment before 2018-05-01
`['and', '>= 2018-04-04', '< 2018-05-01']`	with a next payment between 2018-04-01 and 2018-05-01.

Twig
PHP

{# Fetch subscriptions with a payment due soon #}
{% set aWeekFromNow = date('+7 days')|atom %}

{% set subscriptions = craft.subscriptions()
    .nextPaymentDate("< #{aWeekFromNow}")
    .all() %}

# `offset`

Determines how many subscriptions should be skipped in the results.

Twig
PHP

{# Fetch all subscriptions except for the first 3 #}
{% set subscriptions = craft.subscriptions()
    .offset(3)
    .all() %}

# `onTrial`

Narrows the query results to only subscriptions that are on trial.

Twig
PHP

{# Fetch trialed subscriptions #}
{% set subscriptions = craft.subscriptions()
    .onTrial()
    .all() %}

# `orderBy`

Determines the order that the subscriptions should be returned in. (If empty, defaults to dateCreated DESC.)

Twig
PHP

{# Fetch all subscriptions in order of date created #}
{% set subscriptions = craft.subscriptions()
    .orderBy('dateCreated ASC')
    .all() %}

# `orderId`

Narrows the query results based on the order, per its ID.

Possible values include:

Value	Fetches subscriptions…
`1`	with an order with an ID of 1.
`'not 1'`	not with an order with an ID of 1.
`[1, 2]`	with an order with an ID of 1 or 2.
`['not', 1, 2]`	not with an order with an ID of 1 or 2.

# `plan`

Narrows the query results based on the subscription plan.

Possible values include:

Value	Fetches subscriptions…
`'foo'`	for a plan with a handle of `foo`.
`['foo', 'bar']`	for plans with a handle of `foo` or `bar`.
a Plan (opens new window) object	for a plan represented by the object.

Twig
PHP

{# Fetch Supporter plan subscriptions #}
{% set subscriptions = craft.subscriptions()
    .plan('supporter')
    .all() %}

# `planId`

Narrows the query results based on the subscription plans’ IDs.

Possible values include:

Value	Fetches subscriptions…
`1`	for a plan with an ID of 1.
`[1, 2]`	for plans with an ID of 1 or 2.
`['not', 1, 2]`	for plans not with an ID of 1 or 2.

# `preferSites`

If unique() (opens new window) is set, this determines which site should be selected when querying multi-site elements.

For example, if element “Foo” exists in Site A and Site B, and element “Bar” exists in Site B and Site C, and this is set to ['c', 'b', 'a'], then Foo will be returned for Site C, and Bar will be returned for Site B.

If this isn’t set, then preference goes to the current site.

Twig
PHP

{# Fetch unique subscriptions from Site A, or Site B if they don’t exist in Site A #}
{% set subscriptions = craft.subscriptions()
    .site('*')
    .unique()
    .preferSites(['a', 'b'])
    .all() %}

# `reference`

Narrows the query results based on the reference.

# `relatedTo`

Narrows the query results to only subscriptions that are related to certain other elements.

See Relations (opens new window) for a full explanation of how to work with this parameter.

Twig
PHP

{# Fetch all subscriptions that are related to myCategory #}
{% set subscriptions = craft.subscriptions()
    .relatedTo(myCategory)
    .all() %}

# `search`

Narrows the query results to only subscriptions that match a search query.

See Searching (opens new window) for a full explanation of how to work with this parameter.

Twig
PHP

{# Get the search query from the 'q' query string param #}
{% set searchQuery = craft.app.request.getQueryParam('q') %}

{# Fetch all subscriptions that match the search query #}
{% set subscriptions = craft.subscriptions()
    .search(searchQuery)
    .all() %}

# `status`

Narrows the query results based on the subscriptions’ statuses.

Possible values include:

Value	Fetches subscriptions…
`'active'` (default)	that are active.
`'expired'`	that have expired.

Twig
PHP

{# Fetch expired subscriptions #}
{% set subscriptions = craft.subscriptions()
    .status('expired')
    .all() %}

# `trashed`

Narrows the query results to only subscriptions that have been soft-deleted.

Twig
PHP

{# Fetch trashed subscriptions #}
{% set subscriptions = craft.subscriptions()
    .trashed()
    .all() %}

# `trialDays`

Narrows the query results based on the number of trial days.

# `uid`

Narrows the query results based on the subscriptions’ UIDs.

Twig
PHP

{# Fetch the subscription by its UID #}
{% set subscription = craft.subscriptions()
    .uid('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx')
    .one() %}

# `user`

Narrows the query results based on the subscriptions’ user accounts.

Possible values include:

Value	Fetches subscriptions…
`'foo'`	for a user account with a username of `foo`
`['foo', 'bar']`	for user accounts with a username of `foo` or `bar`.
a User (opens new window) object	for a user account represented by the object.

Twig
PHP

{# Fetch the current user's subscriptions #}
{% set subscriptions = craft.subscriptions()
    .user(currentUser)
    .all() %}

# `userId`

Narrows the query results based on the subscriptions’ user accounts’ IDs.

Possible values include:

Value	Fetches subscriptions…
`1`	for a user account with an ID of 1.
`[1, 2]`	for user accounts with an ID of 1 or 2.
`['not', 1, 2]`	for user accounts not with an ID of 1 or 2.

Twig
PHP

{# Fetch the current user's subscriptions #}
{% set subscriptions = craft.subscriptions()
    .userId(currentUser.id)
    .all() %}

# `with`

Causes the query to return matching subscriptions eager-loaded with related elements.

See Eager-Loading Elements (opens new window) for a full explanation of how to work with this parameter.

Twig
PHP

{# Fetch subscriptions eager-loaded with the "Related" field’s relations #}
{% set subscriptions = craft.subscriptions()
    .with(['related'])
    .all() %}

Subscription Queries

# Example

# Parameters

# anyStatus

# asArray

# clearCachedResult

# dateCanceled

# dateCreated

# dateExpired

# dateSuspended

# dateUpdated

# fixedOrder

# gatewayId

# hasStarted

# id

# ignorePlaceholders

# inReverse

# isCanceled

# isExpired

# isSuspended

# limit

# nextPaymentDate

# offset

# onTrial

# orderBy

# orderId

# plan

# planId

# preferSites

# reference

# relatedTo

# search

# status

# trashed

# trialDays

# uid

# user

# userId

# with

Was this page helpful?

# `anyStatus`

# `asArray`

# `clearCachedResult`

# `dateCanceled`

# `dateCreated`

# `dateExpired`

# `dateSuspended`

# `dateUpdated`

# `fixedOrder`

# `gatewayId`

# `hasStarted`

# `id`

# `ignorePlaceholders`

# `inReverse`

# `isCanceled`

# `isExpired`

# `isSuspended`

# `limit`

# `nextPaymentDate`

# `offset`

# `onTrial`

# `orderBy`

# `orderId`

# `plan`

# `planId`

# `preferSites`

# `reference`

# `relatedTo`

# `search`

# `status`

# `trashed`

# `trialDays`

# `uid`

# `user`

# `userId`

# `with`