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.
- C#
var request = new SubscriptionSearchRequest().
PlanId.Is("the_plan_id");
ResourceCollection<Subscription> collection = gateway.Subscription.Search(request);
foreach (Subscription subscription in collection)
{
Console.WriteLine(subscription.BillingDayOfMonth);
}
If you want to look up a single subscription using its ID, use Subscription: Find
instead.
Parameters
CreatedAt
rangeDaysPastDue
rangeId
textIds
multipleInTrialPeriod
multipleWhether the subscription is in a trial period. Can be true or false. This parameter must be used in conjunction with Status
.
MerchantAccountId
multipleA list of merchant account IDs to search for.
A fragment of the merchant account ID to search for.
Contains
textEndsWith
textIs
textIsNot
textStartsWith
textNextBillingDate
rangePlanId
multiplePrice
rangeStatus
multipleThe status of the subscription. Possible values:
ACTIVE
CANCELED
PAST_DUE
PENDING
EXPIRED
TransactionId
textExamples
Searching by price
Searching on price uses a range field.
- C#
ResourceCollection<Subscription> results = gateway.Subscription.Search(
new SubscriptionSearchRequest().
Price.Between(1M, 2M));
Searching by plan ID
Searching on plan ID uses a multiple value field.
- C#
ResourceCollection<Subscription> results = gateway.Subscription.Search(
new SubscriptionSearchRequest().
PlanId.Is("gold_plan"));
Searching by status
Searching on status uses a multiple value field.
- C#
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.
- C#
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));
Searching by days past due
Searching on days past due uses a range field.
- C#
ResourceCollection<Subscription> results = gateway.Subscription.Search(
new SubscriptionSearchRequest().
DaysPastDue.Between(1, 10));
Searching by merchant account ID
Searching on merchant account ID acts like a multiple value field.
- C#
ResourceCollection<Subscription> results = gateway.Subscription.Search(
new SubscriptionSearchRequest().
MerchantAccountId.IncludedIn("usd_account", "another"));
Searching by 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.
- C#
ResourceCollection<Subscription> results = gateway.Subscription.Search(
new SubscriptionSearchRequest().
BillingCyclesRemaining.GreaterThanOrEqualTo(12.34));
Searching by next billing date
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.
- C#
ResourceCollection<Subscription> collection = gateway.Subscription.Search(
new SubscriptionSearchRequest().
NextBillingDate.LessThanOrEqualTo(DateTime.Now.AddDays(5));
Searching by created-at date/time
Searching on created-at date/time will return subscriptions that were created during the range you have given.
- C#
var searchRequest = new SubscriptionSearchRequest().
CreatedAt.Between(
DateTime.Now.AddDays(-1),
DateTime.Now
);
ResourceCollection<Subscription> collection = gateway.Subscription.Search(searchRequest);
Searching a combination
You can combine any of the search fields into a single search.
- C#
ResourceCollection<Subscription> results = gateway.Subscription.Search(
new SubscriptionSearchRequest()
.PlanId.Is("gold_plan")
.Status.Is(SubscriptionStatus.ACTIVE));