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. Python
collection = gateway.subscription.search(
    braintree.SubscriptionSearch.plan_id == "the_plan_id"
)
for subscription in collection.items:
    print(subscription.billing_day_of_month)
If you want to look up a single subscription using its ID, use Subscription: Find instead.
Parameters
'billing_cycles_remaining'range
The number of billing cycles remaining in the subscription.
'created_at'range
The date/time the subscription was created.
'days_past_due'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.
'in_trial_period'multiple

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

'merchant_account_id'multiple

A list of merchant account IDs to search for.

'merchant_account_id_fragment'

A fragment of the merchant account ID to search for.

'contains'text
A part of the merchant account ID to search for.
'ends_with'text
A postfix for the merchant account ID to search for.
'is'text
An exact merchant account ID to search for.
'is_not'text
A merchant account ID to be excluded from the search.
'starts_with'text
A prefix for the merchant account ID to search for.
'next_billing_date'range
The date the subscription will next be billed.
'plan_id'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
  • PastDue
  • Pending
  • Expired
'transaction_id'text
The transaction ID associated with the subscription.

ExamplesAnchorIcon

Searching by priceAnchorIcon

Searching on price uses a range field.
  1. Python
search_results = gateway.subscription.search(
    braintree.SubscriptionSearch.price >= Decimal("950")
)

Searching by plan IDAnchorIcon

Searching on plan ID uses a multiple value field.
  1. Python
search_results = gateway.subscription.search(
    braintree.SubscriptionSearch.plan_id.in_list("silver_plan", "gold_plan")
)

Searching by statusAnchorIcon

Searching on status uses a multiple value field.
  1. Python
search_results = gateway.subscription.search(
    braintree.SubscriptionSearch.status == braintree.Subscription.Status.Active
)

search_results = gateway.subscription.search(
    braintree.SubscriptionSearch.status.in_list(
        braintree.Subscription.Status.Active,
        braintree.Subscription.Status.Canceled,
        braintree.Subscription.Status.Expired,
        braintree.Subscription.Status.PastDue,
        braintree.Subscription.Status.Pending
    )
)
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. Python
search_results = gateway.subscription.search(
    braintree.SubscriptionSearch.status == braintree.Subscription.Status.Active
)

search_results = gateway.subscription.search(
    braintree.SubscriptionSearch.status == braintree.Subscription.Status.Active,
    braintree.SubscriptionSearch.in_trial_period == True
)

search_results = gateway.subscription.search(
    braintree.SubscriptionSearch.status == braintree.Subscription.Status.Active,
    braintree.SubscriptionSearch.in_trial_period == False
)

Searching by days past dueAnchorIcon

Searching on days past due uses a range field.
  1. Python
search_results = gateway.subscription.search(
    braintree.SubscriptionSearch.days_past_due.between(2, 10)
)
Note
In versions prior to , 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.

Searching by merchant account IDAnchorIcon

Searching on merchant account ID acts like a multiple value field.
  1. Python
search_results = gateway.subscription.search(
    braintree.SubscriptionSearch.merchant_account_id == "usd_merchant_account"
)

Searching by billing cycles remainingAnchorIcon

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. Python
search_results = gateway.subscription.search(
    braintree.SubscriptionSearch.billing_cycles_remaining >= 7
)

Searching by next billing dateAnchorIcon

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. Python
next_billing_date_cutoff = datetime.today() + timedelta(days=5)
search_results = gateway.subscription.search(
    braintree.SubscriptionSearch.next_billing_date <= next_billing_date_cutoff
)

Searching by created-at date/timeAnchorIcon

Searching on created-at date/time will return subscriptions that were created during the range you have given.
  1. Python
search_results = gateway.subscription.search(
    braintree.SubscriptionSearch.created_at.between(
        datetime.datetime.now() - datetime.timedelta(days=1),
        datetime.datetime.now()
    )
)

Searching a combinationAnchorIcon

You can combine any of the search fields into a single search.
  1. Python
search_results = gateway.subscription.search(
    braintree.SubscriptionSearch.plan_id == "gold_plan",
    braintree.SubscriptionSearch.status == braintree.Subscription.Status.Active
)

Searching prior to version 2.5.0AnchorIcon

Prior to version 2.5.0, literal lists must be passed as arguments to all search methods.

  1. Python
search_results = gateway.subscription.search([
    braintree.SubscriptionSearch.plan_id.in_list([
        "silver_plan",
        "gold_plan"
    ])
])

See AlsoAnchorIcon

If you accept cookies, we’ll use them to improve and customize your experience and enable our partners to show you personalized PayPal ads when you visit other sites. Manage cookies and learn more