# Search subscriptions

Use the **searchSubscriptions** method to retrieve details about your account’s subscriptions, based on a set of filters. Subscriptions can be retrieved starting with 5 minutes after their orders are generated in the 2Checkout system.

## Request parameters

<table><thead><tr><th width="134">Parameter</th><th>Type / Description</th></tr></thead><tbody><tr><td><code>sessionID</code></td><td><p><strong>Required (string)</strong></p><p>Session identifier, the output of the <strong>Login</strong> method. Include <code>sessionID</code> into all your requests. 2Checkout throws an exception if the values are incorrect. The <code>sessionID</code> expires in <strong>10 minutes</strong>.</p></td></tr><tr><td><code>searchBy</code></td><td><p><strong>Optional (object)</strong></p><p>Unique, system-generated subscription identifier.</p></td></tr></tbody></table>

### Additional search filters

| SubscriptionSearchOptions parameters | Type / Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CustomerEmail`                      | <p><strong>Optional (string)</strong></p><p>Customer email address. Can be NULL.</p><div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p>The <code>CustomerEmail</code> parameter must be paired always with another reference pointing to the correct customer, such as the <code>2CheckoutCustomerReference</code> parameter or the <code>ExternalCustomerReference</code> parameter. Otherwise, the search call will return partial hits on the customer email address.</p></div> |
| `ExactMatchEmail`                    | <p><strong>Optional (boolean)</strong></p><p>Force search by email to perform exact match; recommended to keep this option set to true in order to avoid matching similar email addresses from multiple customers.</p>                                                                                                                                                                                                                                                                                                |
| `DeliveredCode`                      | <p><strong>Optional (string)</strong></p><p>Activation key/code. Can be NULL.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `2CheckoutCustomerReference`         | <p><strong>Optional (int)</strong></p><p>System-generated customer reference. Can be NULL.</p>                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `ExternalCustomerReference`          | <p><strong>Optional (string)</strong></p><p>External customer reference that you control. Can be NULL.</p>                                                                                                                                                                                                                                                                                                                                                                                                            |
| `Aggregate`                          | <p><strong>Optional (boolean)</strong></p><ul><li><strong>true</strong> - search will work across all your aggregated 2Checkout accounts. </li><li><strong>false</strong> - default value. You limit the search to the account whose details you used for authentication. Can be NULL.</li></ul>                                                                                                                                                                                                                      |
| `SubscriptionEnabled`                | <p><strong>Optional (boolean)</strong></p><ul><li><strong>true</strong> for enabled subscriptions. </li><li><strong>false</strong> for disabled subscriptions. Can be NULL.</li></ul>                                                                                                                                                                                                                                                                                                                                 |
| `RecurringEnabled`                   | <p><strong>Optional (stringArray)</strong></p><ul><li><strong>true</strong> – 2Checkout charges customers using recurring billing for subscriptions. </li><li><strong>false</strong> – customers need to make manual payments to renew their subscriptions. Can be NULL.</li></ul>                                                                                                                                                                                                                                    |
| `ProductCodes`                       | <p><strong>Optional (stringArray)</strong></p><p>Product identifier that you control. Can be NULL.</p>                                                                                                                                                                                                                                                                                                                                                                                                                |
| `CountryCodes`                       | <p><strong>Optional (string)</strong></p><p>Country code (ISO 3166 two-letter code). Can be NULL.</p>                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `PartnerCode`                        | <p><strong>Optional (string)</strong></p><p>Can be NULL.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `PurchasedAfter`                     | <p><strong>Optional (string)</strong></p><p>YYYY-MM-DD. Subscription search interval start. You can search for subscriptions purchased between the dates you set using <code>PurchasedAfter</code> and <code>PurchasedBefore</code>.</p><div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p>The default 2Checkout API time zone is GMT+02:00. Can be NULL.</p></div>                                                                                                                |
| `PurchasedBefore`                    | <p><strong>Optional (string)</strong></p><p>YYYY-MM-DD. Subscription search interval end. You can search for subscriptions purchased between the dates you set using <code>PurchasedAfter</code> and <code>PurchasedBefore</code>.</p><div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p>The default 2Checkout API time zone is GMT+02:00. Can be NULL.</p></div>                                                                                                                  |
| `ExpireAfter`                        | <p><strong>Optional (string)</strong></p><p>YYYY-MM-DD. Search subscriptions set to expire after a specific date.</p><div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p>The default 2Checkout API time zone is GMT+02:00. Can be NULL.</p></div>                                                                                                                                                                                                                                   |
| `ExpireBefore`                       | <p><strong>Optional (string)</strong></p><p>YYYY-MM-DD. Search subscriptions set to expire before a specific date.</p><div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p>The default 2Checkout API time zone is GMT+02:00. Can be NULL.</p></div>                                                                                                                                                                                                                                  |
| `ModifiedAfter`                      | <p><strong>Optional (string)</strong></p><p>YYYY-MM-DD HH-MM-SS. Search subscriptions modified after a specific date.</p>                                                                                                                                                                                                                                                                                                                                                                                             |
| `ModifiedBefore`                     | <p><strong>Optional (string)</strong></p><p>YYYY-MM-DD HH-MM-SS. Search subscriptions modified before a specific date.</p>                                                                                                                                                                                                                                                                                                                                                                                            |
| `RenewedAfter`                       | <p><strong>Optional (string)</strong></p><p>YYYY-MM-DD. Search subscriptions renewed after a specific date.</p><div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p>The default 2Checkout API time zone is GMT+02:00. Can be NULL.</p></div>                                                                                                                                                                                                                                         |
| `RenewedBefore`                      | <p><strong>Optional (string)</strong></p><p>YYYY-MM-DD. Search subscriptions renewed before a specific date.</p><div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p>The default 2Checkout API time zone is GMT+02:00. Can be NULL.</p></div>                                                                                                                                                                                                                                        |
| `NotificationAfter`                  | <p><strong>Optional (string)</strong></p><p>YYYY-MM-DD. Search subscriptions for which the 2Checkout system sent out notifications after a specific date.</p><div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p>The default 2Checkout API time zone is GMT+02:00. Can be NULL.</p></div>                                                                                                                                                                                           |
| `NotificationBefore`                 | <p><strong>Optional (string)</strong></p><p>YYYY-MM-DD. Search subscriptions for which the 2Checkout system sent out notifications before a specific date.</p><div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p>The default 2Checkout API time zone is GMT+02:00. Can be NULL.</p></div>                                                                                                                                                                                          |
| `NextBillingDateAfter`               | <p><strong>Optional (string)</strong></p><p>YYYY-MM-DD. Search subscriptions with the next billing date after the specified date.</p>                                                                                                                                                                                                                                                                                                                                                                                 |
| `NextBillingDateBefore`              | <p><strong>Optional (string)</strong></p><p>YYYY-MM-DD. Search subscriptions with the next billing date before the specified date.</p>                                                                                                                                                                                                                                                                                                                                                                                |
| `Type`                               | <p><strong>Optional (string)</strong></p><ul><li><strong>trial</strong> - trial subscriptions. </li><li><strong>regular</strong> - all generated subscriptions that are not trials. </li><li><strong>regularfromtrial</strong> - subscriptions generated from a trial conversion. Can be NULL.</li></ul>                                                                                                                                                                                                              |
| `TestSubscription`                   | <p><strong>Optional (boolean)</strong></p><p><strong>true</strong> / <strong>false</strong>, depending on whether you want to include test subscriptions in the search or not. Can be NULL.</p>                                                                                                                                                                                                                                                                                                                       |
| `LifetimeSubscription`               | <p><strong>Optional (boolean)</strong></p><ul><li><strong>true</strong> – evergreen subscriptions. </li><li><strong>false</strong> - subscriptions with a limited recurring billing cycle, typically no larger than 36 months. </li></ul><p>Can be NULL.</p>                                                                                                                                                                                                                                                          |
| `Page`                               | <p><strong>Optional (int)</strong></p><p>A specific page of search results. Default value is 1. Can be NULL.</p>                                                                                                                                                                                                                                                                                                                                                                                                      |
| `Limit`                              | <p><strong>Optional (int)</strong></p><p>Number of results (subscriptions) displayed per page. Default value is 10. Can be NULL.</p>                                                                                                                                                                                                                                                                                                                                                                                  |

### Request sample

```php
<?php

require ('PATH_TO_AUTH');

$SubscriptionSearch = new stdClass();
$SubscriptionSearch->CustomerEmail  = 'example@email.com';
$SubscriptionSearch->DeliveredCode = null;
$SubscriptionSearch->AvangateCustomerReference = null;
$SubscriptionSearch->ExternalCustomerReference = null;
$SubscriptionSearch->Aggregate = false;
$SubscriptionSearch->SubscriptionEnabled = null; //true false null
$SubscriptionSearch->RecurringEnabled = null; // true - autorenewal, false - manual renewal, null = both(default)
$SubscriptionSearch->ProductCodes = null; //array('Product_Code1', 'Product_Code2');
$SubscriptionSearch->CountryCodes = null;//array ('au')
$SubscriptionSearch->PurchasedAfter = null;
$SubscriptionSearch->PurchasedBefore = null;
$SubscriptionSearch->ExpireAfter = null;
$SubscriptionSearch->ExpireBefore = null;
$SubscriptionSearch->LifetimeSubscription = null;
$SubscriptionSearch->Type = 'regular'; //'trial', 'regular', 'regularfromtrial'
$SubscriptionSearch->TestSubscription = null; // true, false, null = both(default)
$SubscriptionSearch->Page = 1;
$SubscriptionSearch->Limit = 10;

$jsonRpcRequest = array (
  'method' => 'searchSubscriptions',
  'params' => array($sessionID, $SubscriptionSearch),
  'id' => $i++,
  'jsonrpc' => '2.0'
);

var_dump (callRPC((Object)$jsonRpcRequest, $host, true));
```

## Response parameters

<table><thead><tr><th width="159.5999755859375">Parameter</th><th>Type</th></tr></thead><tbody><tr><td><a href="/pages/4832d693039556476b2c8d99dbf87398de591237"><code>Subscription</code></a></td><td><strong>Array of objects</strong></td></tr></tbody></table>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.2checkout.com/json-rpc-api-reference/json-rpc-api-6.0/api-requests/subscription/search-subscriptions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.