Returns a collection of Braintree_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 = Braintree_Subscription::search([
  Braintree_SubscriptionSearch::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 Braintree_Subscription::find() instead.

Parameters
'billingCyclesRemaining' range

The number of billing cycles remaining in the subscription.

'createdAt' range

The date/time the subscription was created.

'daysPastDue' range

The number of days past due the subscription is.

'id' text

The ID of the subscription.

'ids' multiple

A list of subscription IDs to search for.

'inTrialPeriod' multiple

Whether the subscription is in a trial period. Can be true or false.

'merchantAccountId' multiple

A list of merchant account IDs to search for.

'nextBillingDate' range

The date the subscription will next be billed.

'planId' multiple

A list of plan IDs to search for.

'price' range

The price of the subscription.

'status' multiple

The status of the subscription. Possible values:

  • ACTIVE
  • CANCELED
  • PAST_DUE
  • PENDING
  • EXPIRED
'transactionId' text

The transaction ID associated with the subscription.

Examples

Searching by price

Searching on price uses a range field.

PHP
$collection = Braintree_Subscription::search([
  Braintree_SubscriptionSearch::price()->between('8.00', '12.99')
]);

Searching by plan ID

Searching on plan ID uses a multiple value field.

PHP
$collection = Braintree_Subscription::search([
  Braintree_SubscriptionSearch::planId()->is("gold_plan")
]);

Searching by status

Searching on status uses a multiple value field.

PHP
$collection = Braintree_Subscription::search([
  Braintree_SubscriptionSearch::status()->in(
    [Braintree_Subscription::ACTIVE]
  )
]);

$collection = Braintree_Subscription::search([
  Braintree_SubscriptionSearch::status()->in(
    [
      Braintree_Subscription::ACTIVE,
      Braintree_Subscription::CANCELED,
      Braintree_Subscription::EXPIRED,
      Braintree_Subscription::PAST_DUE,
      Braintree_Subscription::PENDING
    ]
  )
]);
note

The past due constant (Braintree_Subscription::PAST_DUE) is wrong in version 2.3 of the PHP library and prior. To search on past due status, use the string 'Past Due'.

PHP
$collection = Braintree_Subscription::search([
  Braintree_SubscriptionSearch::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 = Braintree_Subscription::search([
  Braintree_SubscriptionSearch::status()->in(
    [Braintree_Subscription::ACTIVE]
  )
]);
$collection = Braintree_Subscription::search([
  Braintree_SubscriptionSearch::status()->in(
    [Braintree_Subscription::ACTIVE]
  ),
  Braintree_SubscriptionSearch::inTrialPeriod()->is(true)
]);
$collection = Braintree_Subscription::search([
  Braintree_SubscriptionSearch::status()->in(
    [Braintree_Subscription::ACTIVE]
  ),
  Braintree_SubscriptionSearch::inTrialPeriod()->is(false)
]);

Searching by days past due

Searching on days past due uses a range field.

PHP
$collection = Braintree_Subscription::search([
  Braintree_SubscriptionSearch::daysPastDue()->between(5, 10)
]);

Searching by merchant account ID

Searching on merchant account ID acts like a multiple value field.

PHP
$collection = Braintree_Subscription::search([
  Braintree_SubscriptionSearch::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 = Braintree_Subscription::search([
  Braintree_SubscriptionSearch::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 = Braintree_Subscription::search([
    Braintree_SubscriptionSearch::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 = Braintree_Subscription::search([
  Braintree_SubscriptionSearch::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 = Braintree_Subscription::search([
    Braintree_SubscriptionSearch::planId()->endsWith("rial_plan"),
    Braintree_SubscriptionSearch::daysPastDue()->is("3"),
]);

See also

Still have questions?

If you can’t find an answer, contact our Support team.