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.

SubscriptionSearchRequest request = new SubscriptionSearchRequest().
  price().between(new BigDecimal(5), new BigDecimal(15));

ResourceCollection<Subscription> collection = gateway.subscription().search(request);

Plan ID

Searching on plan id uses a multiple value field.

SubscriptionSearchRequest request = new SubscriptionSearchRequest().
    planId().is("gold_plan");

ResourceCollection<Subscription> collection = gateway.subscription().search(request);

Status

Searching on status uses a multiple value field.

SubscriptionSearchRequest request = new SubscriptionSearchRequest().
    status().is(Subscription.Status.ACTIVE);

SubscriptionSearchRequest request = new SubscriptionSearchRequest().
    status().in(
        Subscription.Status.ACTIVE,
        Subscription.Status.CANCELED,
        Subscription.Status.EXPIRED,
        Subscription.Status.PAST_DUE,
        Subscription.Status.PENDING
    );

ResourceCollection<Subscription> collection = gateway.subscription().search(request);

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.

SubscriptionSearchRequest request = new SubscriptionSearchRequest().
    status().is(Subscription.Status.ACTIVE);

SubscriptionSearchRequest request = new SubscriptionSearchRequest().
	status().is(Subscription.Status.ACTIVE)
	InTrialPeriod().is(true);

SubscriptionSearchRequest request = new SubscriptionSearchRequest().
	status().is(Subscription.Status.ACTIVE)
	 InTrialPeriod().is(false);

Days Past Due

Searching on days past due uses a range field.

SubscriptionSearchRequest request = new SubscriptionSearchRequest().
  daysPastDue().greaterThanOrEqualTo(42);

ResourceCollection<Subscription> collection = gateway.subscription().search(request);

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.

SubscriptionSearchRequest request = new SubscriptionSearchRequest().
  merchantAccountId().in("42", "43");

ResourceCollection<Subscription> collection = gateway.subscription().search(request);

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.

SubscriptionSearchRequest request = new SubscriptionSearchRequest().
  billingCyclesRemaining().between(1, 2);

ResourceCollection<Subscription> collection = gateway.subscription().search(request);

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.

Calendar expectedNextBillingDate = Calendar.getInstance();
expectedNextBillingDate.add(Calendar.DAY_OF_MONTH, 5);

SubscriptionSearchRequest search = new SubscriptionSearchRequest().
    nextBillingDate().lessThanOrEqualTo(expectedNextBillingDate);
ResourceCollection<Subscription> results = gateway.subscription().search(search);

Combination

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

SubscriptionSearchRequest request = new SubscriptionSearchRequest().
    planId().is("gold_plan").
    status().is(Subscription.Status.ACTIVE);

ResourceCollection<Subscription> collection = gateway.subscription().search(request);

See Also