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.

  1. Ruby
collection = gateway.subscription.search do |search|
  search.plan_id.is "the_plan_id"
end

collection.each do |subscription|
  puts subscription.billing_day_of_month
end

If you want to look up a single subscription using its ID, use Subscription: Find instead.

Parameters
:billing_cycles_remainingrange
The number of billing cycles remaining in the subscription.
:created_atrange
The date/time the subscription was created.
:days_past_duerange
The number of days past due the subscription is.
:idtext
The ID of the subscription.
:idsmultiple
A list of subscription IDs to search for.
:in_trial_periodmultiple

Whether the subscription is in a trial period. Can be true or false. This parameter must be used in conjunction with status.

:merchant_account_idmultiple

A list of merchant account IDs to search for.

:merchant_account_id_fragment

A fragment of the merchant account ID to search for.

:containstext
A part of the merchant account ID to search for.
:ends_withtext
A postfix for the merchant account ID to search for.
:istext
An exact merchant account ID to search for.
:is_nottext
A merchant account ID to be excluded from the search.
:starts_withtext
A prefix for the merchant account ID to search for.
:next_billing_daterange
The date the subscription will next be billed.
:plan_idmultiple
A list of plan IDs to search for.
:pricerange
The price of the subscription.
:statusmultiple

The status of the subscription. Possible values:

  • Active
  • Canceled
  • PastDue
  • Pending
  • Expired
:transaction_idtext
The transaction ID associated with the subscription.

Examplesanchor

Searching by priceanchor

Searching on price uses a range field.

  1. Ruby
search_results = gateway.subscription.search do |search|
  search.price <= 5
end

search_results = gateway.subscription.search do |search|
  search.price.between 3, 10
end

Searching by plan IDanchor

Searching on plan ID uses a multiple value field.

  1. Ruby
search_results = gateway.subscription.search do |search|
  search.plan_id.is "gold_plan"
end

search_results = gateway.subscription.search do |search|
  search.plan_id.in "silver_plan", "gold_plan"
end

Searching by statusanchor

Searching on status uses a multiple value field.

  1. Ruby
search_results = gateway.subscription.search do |search|
  search.status.is Braintree::Subscription::Status::Active
end

search_results = gateway.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.

  1. Ruby
search_results = gateway.subscription.search do |search|
  search.status.is Braintree::Subscription::Status::Active
end

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

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

Searching by days past dueanchor

Searching on days past due uses a range field.

  1. Ruby
search_results = gateway.subscription.search do |search|
  search.days_past_due <= 5
end

search_results = gateway.subscription.search do |search|
  search.days_past_due.between 1, 5
end

Searching by merchant account IDanchor

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

  1. Ruby
search_results = gateway.subscription.search do |search|
  search.merchant_account_id.in "usd_merchant_account", "another"
end

Searching by billing cycles remaininganchor

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.

  1. Ruby
search_results = gateway.subscription.search do |search|
  search.billing_cycles_remaining <= 5
end

Searching by next billing dateanchor

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.

  1. Ruby
five_days_from_now = Time.now + (5 * 24 * 60 * 60)
search_results = gateway.subscription.search do |search|
  search.next_billing_date <= five_days_from_now
end

Searching by created-at date/timeanchor

Searching on created-at date/time will return subscriptions that were created during the range you have given.

  1. Ruby
search_results = gateway.subscription.search do |search|
  search.created_at.between(
    Time.now - 60*60*24,
    Time.now
	 )
end

Searching a combinationanchor

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

  1. Ruby
search_results = gateway.subscription.search do |search|
  search.plan_id.is "gold_plan"
  search.status.is "Active"
end

See also