Searching for Subscriptions

If you want to look up a single subscription using its ID, use the find method.

$subscription = Braintree_Subscription::find('a_subscription_id');

Otherwise, you can search for subscriptions using a variety of criteria. For operators available on search fields, see the search fields page.

Price

Searching on price uses a range field.

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

Plan ID

Searching on plan id uses a multiple value field.

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

Status

Searching on status uses a multiple value field.

$collection = Braintree_Subscription::search(array(
  Braintree_SubscriptionSearch::status()->in(
    array(Braintree_Subscription::ACTIVE)
  )
));

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

Bug: 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'.

$collection = Braintree_Subscription::search(array(
  Braintree_SubscriptionSearch::status()->in(
    array('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.

$collection = Braintree_Subscription::search(array(
  Braintree_SubscriptionSearch::status()->in(
    array(Braintree_Subscription::ACTIVE)
  )
));
$collection = Braintree_Subscription::search(array(
  Braintree_SubscriptionSearch::status()->in(
    array(Braintree_Subscription::ACTIVE)
  ),
  Braintree_SubscriptionSearch::inTrialPeriod()->is(true)
));
$collection = Braintree_Subscription::search(array(
  Braintree_SubscriptionSearch::status()->in(
    array(Braintree_Subscription::ACTIVE)
  ),
  Braintree_SubscriptionSearch::inTrialPeriod()->is(false)
));

Days Past Due

Searching on days past due uses a range field.

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

Note In versions prior to 2.5.0, you can only search on days past due as a specific number, rather than using a range search. For these versions, if you want subscriptions that have been past due between 1 and 5 days, you will need to run 5 searches.

Merchant Account ID

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

$collection = Braintree_Subscription::search(array(
  Braintree_SubscriptionSearch::merchantAccountId()->in(
    array("usd_account", "another")
  )
));

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.

$collection = Braintree_Subscription::search(array(
  Braintree_SubscriptionSearch::billingCyclesRemaining()->between(5, 10)
));

Next Billing Date

Searching on next billing date will return subscriptions that will bill again based upon the date range you have given it. The example below will return any subscriptions who will be billed in the next five days.

$fiveDaysFromNow = new DateTime();
$fiveDaysFromNow->modify("+5 days");

$collection = Braintree_Subscription::search(array(
    Braintree_SubscriptionSearch::nextBillingDate()->lessThanOrEqualTo($fiveDaysFromNow)
));

Combination

You can combine any of the search fields into a single search.

$collection = Braintree_Subscription::search(array(
    Braintree_SubscriptionSearch::planId()->endsWith("rial_plan"),
    Braintree_SubscriptionSearch::daysPastDue()->is("3"),
));

See Also