Subscription Queries
You can fetch subscriptions in your templates or PHP code using subscription queries.
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.
{# 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.
{# 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. |
{# 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. |
{# 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. |
{# 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. |
{# 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. |
{# 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.
{# 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.
{# 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. |
{# 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.
{# Fetch subscriptions in reverse #}
{% set subscriptions = craft.subscriptions()
.inReverse()
.all() %}
# isCanceled
Narrows the query results to only subscriptions that are canceled.
{# Fetch canceled subscriptions #}
{% set subscriptions = craft.subscriptions()
.isCanceled()
.all() %}
# isExpired
Narrows the query results to only subscriptions that have expired.
{# Fetch expired subscriptions #}
{% set subscriptions = craft.subscriptions()
.isExpired()
.all() %}
# isSuspended
Narrows the query results to only subscriptions that are suspended.
{# Fetch suspended subscriptions #}
{% set subscriptions = craft.subscriptions()
.isSuspended()
.all() %}
# limit
Determines the number of subscriptions that should be returned.
{# 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. |
{# 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.
{# 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.
{# 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
.)
{# 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. |
{# 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.
{# 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.
{# 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.
{# 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. |
{# Fetch expired subscriptions #}
{% set subscriptions = craft.subscriptions()
.status('expired')
.all() %}
# trashed
Narrows the query results to only subscriptions that have been soft-deleted.
{# 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.
{# 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. |
{# 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. |
{# 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.