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.

search_results = Braintree::Subscription.search do |search|
  search.price <= 5
end

search_results = Braintree::Subscription.search do |search|
  search.price.between 3, 10
end

Plan ID

Searching on plan id uses a multiple value field.

search_results = Braintree::Subscription.search do |search|
  search.plan_id.is "gold_plan"
end

search_results = Braintree::Subscription.search do |search|
  search.plan_id.in "silver_plan", "gold_plan"
end

Status

Searching on status uses a multiple value field.

search_results = Braintree::Subscription.search do |search|
  search.status.is Braintree::Subscription::Status::Active
end

search_results = Braintree::Subscription.search do |search|
  search.status.in(
    Braintree::Subscription::Status::Active,
    Braintree::Subscription::Status::Canceled,
    Braintree::Subscription::Status::Expired,
    Braintree::Subscription::Status::PastDue,
    Braintree::Subscription::Status::Pending
  )
end

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.

search_results = Braintree::Subscription.search do |search|
  search.status.is Braintree::Subscription::Status::Active
end

search_results = Braintree::Subscription.search do |search|
  search.status.is Braintree::Subscription::Status::Active
  search.in_trial_period true
end

search_results = Braintree::Subscription.search do |search|
  search.status.is Braintree::Subscription::Status::Active
  search.in_trial_period false
end

Days Past Due

Searching on days past due uses a range field.

search_results = Braintree::Subscription.search do |search|
  search.days_past_due <= 5
end

search_results = Braintree::Subscription.search do |search|
  search.days_past_due.between 1, 5
end

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.

search_results = Braintree::Subscription.search do |search|
  search.merchant_account_id.in "usd_merchant_account", "another"
end

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.

search_results = Braintree::Subscription.search do |search|
  search.billing_cycles_remaining <= 5
end

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.

five_days_from_now = Time.now + (5 * 24 * 60 * 60)
search_results = Braintree::Subscription.search do |search|
  search.next_billing_date <= five_days_from_now
end

Combination

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

search_results = Braintree::Subscription.search do |search|
  search.plan_id.is "gold_plan"
  search.status.is "active"
end

See Also