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.

Node

const stream = gateway.subscription.search((search) => {
    search.planId().is("the_plan_id");
}, (err, response) => {
    response.each((err, subscription) => {
        console.log(subscription.billingDayOfMonth);
    });
});

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

Parameters

billingCyclesRemainingrange

The number of billing cycles remaining in the subscription.

createdAtrange

The date/time the subscription was created.

daysPastDuerange

The number of days past due the subscription is.

idtext

The ID of the subscription.

idsmultiple

A list of subscription IDs to search for.

inTrialPeriodmultiple

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

merchantAccountIdmultiple

A list of merchant account IDs to search for.

merchantAccountIdFragment

A fragment of the merchant account ID to search for.

containstext

A part of the merchant account ID to search for.

endsWithtext

A postfix for the merchant account ID to search for.

istext

An exact merchant account ID to search for.

isNottext

A merchant account ID to be excluded from the search.

startsWithtext

A prefix for the merchant account ID to search for.

nextBillingDaterange

The date the subscription will next be billed.

planIdmultiple

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

transactionIdtext

The transaction ID associated with the subscription.

Search results

All examples assume version or greater. The search method returns a node stream and can be consumed as any other stream.

Node

const stream = gateway.subscription.search((search) => {
    search.price().between(5, 15);
});

stream.pipe(someWritableStream);

Node

const stream = gateway.subscription.search((search) => {
    search.price().between(5, 15);
});

stream.on("data", (subscription) => {
    // ...
});

stream.on("end", () => {
    // ...
});

stream.resume();

An example of searching prior to version can be found on the search results page.

Examples

Searching by price

Searching on price uses a range field.

Node

const stream = gateway.subscription.search((search) => {
    search.price().between(5, 15);
});

Searching by plan ID

Searching on plan ID uses a multiple value field.

Node

const stream = gateway.subscription.search((search) => {
    search.planId().is("goldPlan");
});

Searching by status

Searching on status uses a multiple value field.

Node

const stream = gateway.subscription.search((search) => {
    search.status().is(braintree.Subscription.Status.Active);
});

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.

Node

const stream = gateway.subscription.search((search) => {
    search.status().is(braintree.Subscription.Status.Active);
});

Node

const stream = gateway.subscription.search((search) => {
    search.status().is(braintree.Subscription.Status.Active);
    search.inTrialPeriod().is(true);
});

Node

const stream = gateway.subscription.search((search) => { search.status().is(braintree.Subscription.Status.Active); search.inTrialPeriod().is(false); });

Searching by days past due

Searching on days past due uses a range field.

Node

const stream = gateway.subscription.search((search) => {
    search.daysPastDue().min(42);
});

Searching by merchant account ID

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

Node

const stream = gateway.subscription.search((search) => {
    search.merchantAccountId().in("42", "43");
});

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.

Node

const stream = gateway.subscription.search((search) => {
    search.billingCyclesRemaining().between(1, 2);
});

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.

Node

const today = new Date();
const fiveDaysFromNow = new Date();
fiveDaysFromNow.setDate(today.getDate() + 5);
const stream = gateway.subscription.search((search) => {
    search.nextBillingDate().max(fiveDaysFromNow);
});

Searching by created-at date/time

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

Node

const today = new Date();
const yesterday = new Date();
yesterday.setDate(today.getDate() - 1);
const stream = gateway.subscription.search((search) => {
    search.createdAt().between(yesterday, today);
});

Searching a combination

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

Node

const stream = gateway.subscription.search((search) => {
    search.planId().is("goldPlan");
    search.status().is(braintree.Subscription.Status.Active);
});

Subscription

Subscription: Search

Parameters

Search results

Examples

Searching by price

Searching by plan ID

Searching by status

Searching by days past due

Searching by merchant account ID

Searching by billing cycles remaining

Searching by next billing date

Searching by created-at date/time

Searching a combination

See Also