Subscription
Subscription: Search
Returns a collection of Subscription response objects.
You can search for subscriptions using a variety of criteria. For operators available on search fields, see the search fields page.
- PHP
$collection = $gateway->subscription()->search([
BraintreeSubscriptionSearch::planId()->is("the_plan_id")
]);
foreach($collection as $subscription) {
echo $subscription->billingDayOfMonth;
}
If you want to look up a single subscription using its ID, use Subscription: Find
instead.
Parameters
'createdAt'
range'daysPastDue'
range'id'
text'ids'
multiple'inTrialPeriod'
multipleWhether the subscription is in a trial period. Can be true or false. This parameter must be used in conjunction with status
.
'merchantAccountId'
multipleA list of merchant account IDs to search for.
A fragment of the merchant account ID to search for.
'contains'
text'endsWith'
text'is'
text'isNot'
text'startsWith'
text'nextBillingDate'
range'planId'
multiple'price'
range'status'
multipleThe status of the subscription. Possible values:
ACTIVE
CANCELED
PAST_DUE
PENDING
EXPIRED
'transactionId'
textExamples
Searching by price
Searching on price uses a range field.
- PHP
$collection = $gateway->subscription()->search([
BraintreeSubscriptionSearch::price()->between('8.00', '12.99')
]);
Searching by plan ID
Searching on plan ID uses a multiple value field.
- PHP
$collection = $gateway->subscription()->search([
BraintreeSubscriptionSearch::planId()->is("gold_plan")
]);
Searching by status
Searching on status uses a multiple value field.
- PHP
$collection = $gateway->subscription()->search([
BraintreeSubscriptionSearch::status()->in(
[BraintreeSubscription::ACTIVE]
)
]);
$collection = $gateway->subscription()->search([
BraintreeSubscriptionSearch::status()->in(
[
BraintreeSubscription::ACTIVE,
BraintreeSubscription::CANCELED,
BraintreeSubscription::EXPIRED,
BraintreeSubscription::PAST_DUE,
BraintreeSubscription::PENDING
]
)
]);
- PHP
$collection = $gateway->subscription()->search([
BraintreeSubscriptionSearch::status()->in(
['Past Due']
)
]);
When searching for subscriptions that are active, you have the ability to search for all active subscriptions (with or without a trial period), subscriptions with a trial period, or subscriptions without a trial period.
- PHP
$collection = $gateway->subscription()->search([
BraintreeSubscriptionSearch::status()->in(
[BraintreeSubscription::ACTIVE]
)
]);
$collection = $gateway->subscription()->search([
BraintreeSubscriptionSearch::status()->in(
[BraintreeSubscription::ACTIVE]
),
BraintreeSubscriptionSearch::inTrialPeriod()->is(true)
]);
$collection = $gateway->subscription()->search([
BraintreeSubscriptionSearch::status()->in(
[BraintreeSubscription::ACTIVE]
),
BraintreeSubscriptionSearch::inTrialPeriod()->is(false)
]);
Searching by days past due
Searching on days past due uses a range field.
- PHP
$collection = $gateway->subscription()->search([
BraintreeSubscriptionSearch::daysPastDue()->between(5, 10)
]);
Searching by merchant account ID
Searching on merchant account ID acts like a multiple value field.
- PHP
$collection = $gateway->subscription()->search([
BraintreeSubscriptionSearch::merchantAccountId()->in(
["usd_account", "another"]
)
]);
Searching by billing cycles remaining
Searching on billing cycles remaining will find subscriptions which have a set limit to the number of times they will recur. It uses a range field.
- PHP
$collection = $gateway->subscription()->search([
BraintreeSubscriptionSearch::billingCyclesRemaining()->between(5, 10)
]);
Searching by next billing date
Searching on next billing date will return subscriptions that will bill again during the date range you have given it. The example below will return any subscriptions that will be billed in the next five days.
- PHP
$fiveDaysFromNow = new DateTime();
$fiveDaysFromNow->modify("+5 days");
$collection = $gateway->subscription()->search([
BraintreeSubscriptionSearch::nextBillingDate()->lessThanOrEqualTo($fiveDaysFromNow)
]);
Searching by created-at date/time
Searching on created-at date/time will return subscriptions that were created during the range you have given.
- PHP
$searchResults = $gateway->subscription()->search([
BraintreeSubscriptionSearch::createdAt()->between(
new DateTime('-1 day'),
new DateTime()
)
]);
Searching a combination
You can combine any of the search fields into a single search.
- PHP
$collection = $gateway->subscription()->search([
BraintreeSubscriptionSearch::planId()->endsWith("rial_plan"),
BraintreeSubscriptionSearch::daysPastDue()->is("3"),
]);