Searching for Subscriptions

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

Subscription subscription = gateway.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.

ResourceCollection<Subscription> results = gateway.Subscription.Search(
  new SubscriptionSearchRequest().
    Price.Between(1M, 2M));

Plan ID

Searching on plan id uses a multiple value field.

ResourceCollection<Subscription> results = gateway.Subscription.Search(
  new SubscriptionSearchRequest().
    PlanId.Is("gold_plan"));

Status

Searching on status uses a multiple value field.

ResourceCollection<Subscription> results = gateway.Subscription.Search(
  new SubscriptionSearchRequest().
    Status.Is(SubscriptionStatus.ACTIVE));

results = gateway.Subscription.Search(
  new SubscriptionSearchRequest().
    Status.IncludedIn(
      SubscriptionStatus.ACTIVE,
      SubscriptionStatus.CANCELED,
      SubscriptionStatus.EXPIRED,
      SubscriptionStatus.PAST_DUE,
      SubscriptionStatus.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.

ResourceCollection<Subscription> results = gateway.Subscription.Search(
  new SubscriptionSearchRequest().
    Status.Is(SubscriptionStatus.ACTIVE));

ResourceCollection<Subscription> results = gateway.Subscription.Search(
  new SubscriptionSearchRequest().
	Status.Is(SubscriptionStatus.ACTIVE)).
    InTrialPeriod.Is(true);

ResourceCollection<Subscription> results = gateway.Subscription.Search(
  new SubscriptionSearchRequest().
	Status.Is(SubscriptionStatus.ACTIVE).
    InTrialPeriod.Is(false));

Days Past Due

Searching on days past due uses a range field.

ResourceCollection<Subscription> results = gateway.Subscription.Search(
  new SubscriptionSearchRequest().
    DaysPastDue.Between(1, 10));

Note In versions prior to 2.6.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.

ResourceCollection<Subscription> results = gateway.Subscription.Search(
  new SubscriptionSearchRequest().
    MerchantAccountId.IncludedIn("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.

ResourceCollection<Subscription> results = gateway.Subscription.Search(
  new SubscriptionSearchRequest().
    BillingCyclesRemaining.GreaterThanOrEqualTo(12.34));

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.

ResourceCollection<Subscription> collection = gateway.Subscription.Search(
  new SubscriptionSearchRequest().
    NextBillingDate.LessThanOrEqualTo(DateTime.Now.AddDays(5));

Combination

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

ResourceCollection<Subscription> results = gateway.Subscription.Search(
    new SubscriptionSearchRequest().
        PlanId.Is("gold_plan").
        Status.Is(SubscriptionStatus.ACTIVE));

See Also