Search Subscriptions API

Overview of the endpoint

The POST /subscriptions/search endpoint retrieves a paginated list of Subscriptions with support for:

• Free-text search — search across Subscription name, Offer name, Vendor name, External Subscription ID, Subscription ID, Domain Name, and Tenant.
• Multi-field filtering — filter by status, Customer, Offer and Seller, using enum values and GUIDs. The available filter values can be retrieved with the filters endpoint.
• Expiration and Renewal windows — limit results to Subscriptions expiring or auto-renewing within a specified number of days via the NDaysCount parameter.
• Pagination — page through large result sets using Page and PageSize parameters (up to 1000 results per page). The Total field in the response indicates the full count of matching Subscriptions across all pages.

Request details

Method and route:

POST https://api.appxite.com/subscription/subscriptions/search

Headers

Result scope

The set of Subscriptions returned depends on the headers and on whether DistributorId is passed in the request body:

The SubscriptionTier of each returned Subscription shows where it comes from: Direct means a Subscription from the current platform (the platform identified by X-Referer); Indirect means a Subscription from the platform of 2-tier Sellers, which is returned only when X-Referer is a Distributor platform.

Request body parameters

Retrieving filter values

To find out which values can be used in the Filters array, call the Retrieve subscription search filters endpoint. It returns the filter values available for the Subscription grid:

POST https://api.appxite.com/subscription/subscriptions/search/filters

The endpoint uses the same headers as the search endpoint: X-Referer (the current platform) is required, and X-On-Behalf-Of is optional; when it is passed, the values are scoped to that Customer's Subscriptions. In the request body, pass DistributorId to get the filter values for the Channel View. The other body parameters (Page, PageSize, Query, Filters, NDaysCount) are optional.

{
    "DistributorId": "d4e5f6a7-b8c9-0123-def0-555555555555"
}

The response lists the available values for each filter. Name is the display name and Value is the value to use in the Filters array of the search request. For example, the status "Enabled" has the value 1. The example below is shortened:

{
    "FiltersValues": {
        "Status": [
            { "Name": "Disabled", "Value": "0" },
            { "Name": "Enabled", "Value": "1" }
        ],
        "ScheduledActionType": [
            { "Name": "RenewToNewTerm", "Value": "0" },
            { "Name": "Cancel", "Value": "1" },
            { "Name": "RenewToExtendedServiceTerm", "Value": "2" }
        ]
    }
}

Request examples

Example 1 — Single filter by Offer

This request retrieves page 1 with 20 results, filtering Subscriptions by two specific Offers (field value 2), with an expiration/Renewal window of 30 days.

{
    "Page": 1,
    "PageSize": 20,
    "Query": "",
    "Filters": [
        {
            "Field": 2,
            "Filters": [
                "f6f6f6f6-a7a7-b8b8-c9c9-d0d0d0d0d0d0",
                "d5d5d5d5-e6e6-f7f7-a8a8-b9b9b9b9b9b9"
            ]
        }
    ],
    "NDaysCount": 30
}

Example 2 — Multiple filters combined (Offer + Status)

This request combines two filters: only active Subscriptions (Status 1 = Enabled) of a specific Offer (field value 2). Both conditions must be met (AND logic).

{
    "Page": 1,
    "PageSize": 20,
    "Query": "",
    "Filters": [
        {
            "Field": 2,
            "Filters": ["f6f6f6f6-a7a7-b8b8-c9c9-d0d0d0d0d0d0"]
        },
        {
            "Field": "Status",
            "Filters": [1]
        }
    ]
}

Example 3 — Free-text search using Query

This request searches for Subscriptions matching the keyword "Office 365" across searchable fields (Subscription name, Offer name, Vendor name, Domain Name, Tenant, and Subscription IDs). Filters can be combined with Query for further refinement.

{
    "Page": 1,
    "PageSize": 20,
    "Query": "Office 365",
    "Filters": []
}

Example 4 — Combining Query with filters and NDaysCount

This request searches for "Azure" within active Subscriptions (Status 1 = Enabled) of a specific Customer (field value 18) that are expiring or auto-renewing within 60 days.

{
    "Page": 1,
    "PageSize": 20,
    "Query": "Azure",
    "Filters": [
        {
            "Field": "Status",
            "Filters": [1]
        },
        {
            "Field": 18,
            "Filters": ["b2c3d4e5-f6a7-8901-bcde-333333333333"]
        }
    ],
    "NDaysCount": 60
}

Example 5 — Channel View: filter by Seller

This request filters Subscriptions managed by a specific Seller (field value 26) in the channel. This is useful for Distributors who want to view Subscriptions of a particular Seller programmatically, matching the Channel View functionality in the UI. The Distributor is identified by DistributorId in the request body; do not send the X-On-Behalf-Of header.

{
    "Page": 1,
    "PageSize": 20,
    "Query": "",
    "Filters": [
        {
            "Field": 26,
            "Filters": ["c3d4e5f6-a7b8-9012-cdef-444444444444"]
        },
        {
            "Field": "Status",
            "Filters": [1]
        }
    ],
    "DistributorId": "d4e5f6a7-b8c9-0123-def0-555555555555"
}

Response structure

A successful request returns a 200 OK response containing a paginated list of Subscriptions.

Subscription object fields

Each Subscription object in the Items array contains the following fields:

Example response

{
    "Total": 2,
    "Items": [
        {
            "Id": "a1a1a1a1-b2b2-c3c3-d4d4-e5e5e5e5e5e5",
            "Status": "Enabled",
            "Name": "Enterprise Cloud Suite",
            "OfferId": "f6f6f6f6-a7a7-b8b8-c9c9-d0d0d0d0d0d0",
            "OfferName": "Enterprise Cloud Suite",
            "VendorId": "a1b2c3d4-e5f6-7890-abcd-111111111111",
            "Vendor": "Microsoft",
            "Tenant": "e1e1e1e1-f2f2-a3a3-b4b4-c5c5c5c5c5c5",
            "DomainName": "contoso.onmicrosoft.com",
            "IncludeTenants": [],
            "MinimumCommitmentMonths": 0,
            "VendorWithTenant": "Microsoft | e1e1e1e1-f2f2-a3a3-b4b4-c5c5c5c5c5c5 | contoso.onmicrosoft.com",
            "ExpirationTimestamp": "2027-06-15T00:00:00Z",
            "Quantity": 25,
            "AddonsQuantity": 2,
            "OfferType": "LicenceBasedSubscription",
            "IsTrial": false,
            "IsSubscriptionAutoRenewEnabled": true,
            "SubscriptionNameOfferTooltipLabel": null,
            "SubscriptionRenewConfigStatus": "Active",
            "ExternalSubscriptionId": "EXT-0001-ABCD-1234",
            "CustomerId": "b2c3d4e5-f6a7-8901-bcde-333333333333",
            "CustomerName": "Contoso Ltd",
            "CustomerExternalId": null,
            "CustomerReferenceNumber": 10042,
            "CatalogMarkup": 8.50,
            "SubscriptionMarkup": 0,
            "PriceSource": "ResellerInPrice",
            "ExpirationStatus": "None",
            "SubscriptionTier": "Direct",
            "ScheduledActionType": "RenewToNewTerm",
            "ResellerId": "c3d4e5f6-a7b8-9012-cdef-444444444444",
            "ResellerShortName": "Northwind Traders",
            "ResellerFullName": "Northwind Traders Ltd",
            "ResellerCountryName": "Germany",
            "DistributorId": null,
            "CustomerUsageCost": null
        },
        {
            "Id": "b2b2b2b2-c3c3-d4d4-e5e5-f6f6f6f6f6f6",
            "Status": "Enabled",
            "Name": "Cloud Security Platform",
            "OfferId": "d5d5d5d5-e6e6-f7f7-a8a8-b9b9b9b9b9b9",
            "OfferName": "Cloud Security Platform",
            "VendorId": "a1b2c3d4-e5f6-7890-abcd-222222222222",
            "Vendor": "Bitdefender",
            "Tenant": null,
            "DomainName": "sec-contoso-001",
            "IncludeTenants": [],
            "MinimumCommitmentMonths": 0,
            "VendorWithTenant": "Bitdefender | sec-contoso-001",
            "ExpirationTimestamp": "2027-09-30T00:00:00Z",
            "Quantity": 50,
            "AddonsQuantity": 0,
            "OfferType": "QuantityBasedOneTimeBilledOffer",
            "IsTrial": false,
            "IsSubscriptionAutoRenewEnabled": true,
            "SubscriptionNameOfferTooltipLabel": null,
            "SubscriptionRenewConfigStatus": "Active",
            "ExternalSubscriptionId": "EXT-0002-EFGH-5678",
            "CustomerId": "b2c3d4e5-f6a7-8901-bcde-333333333333",
            "CustomerName": "Contoso Ltd",
            "CustomerExternalId": null,
            "CustomerReferenceNumber": 10042,
            "CatalogMarkup": 0,
            "SubscriptionMarkup": 0,
            "PriceSource": "VendorRetailPrice",
            "ExpirationStatus": "None",
            "SubscriptionTier": "Direct",
            "ScheduledActionType": "RenewToNewTerm",
            "ResellerId": "c3d4e5f6-a7b8-9012-cdef-444444444444",
            "ResellerShortName": "Northwind Traders",
            "ResellerFullName": "Northwind Traders Ltd",
            "ResellerCountryName": "Germany",
            "DistributorId": null,
            "CustomerUsageCost": null
        }
    ]
}

Error handling

Errors are returned using standard HTTP status codes.

Best practices

Follow these recommendations to get the most out of the Search Subscriptions endpoint and avoid common issues.  

Use pagination for large datasets

Always implement pagination rather than requesting all Subscriptions in a single call. The maximum PageSize is 1000. For interactive use, start with a smaller PageSize (for example, 20–50); for bulk extraction, larger pages (up to 1000) reduce the number of calls. Use the Total value in the response to calculate how many pages you need to iterate through.

Combine filters to narrow results early

Rather than retrieving all Subscriptions and filtering client-side, use the Filters array to narrow results at the API level. Combining multiple filters (for example, Status + Customer) reduces the payload size and improves response times. This is especially important for Distributors with large sales channels where unfiltered results can contain thousands of records.

Use Query for user-driven search, Filters for automated workflows

The Query parameter is designed for broad, keyword-based searches — ideal when a user types a search term and expects results across multiple fields. For automated integrations and scheduled reporting, prefer Filters with exact identifiers (GUIDs) for precise, repeatable results. You can combine both when needed: for example, use a Query to search by name within a specific Offer filter.

Use NDaysCount for renewal and expiration monitoring

The NDaysCount parameter is the most efficient way to build automated Renewal alerts or expiration reports. Instead of retrieving all Subscriptions and comparing dates client-side, set NDaysCount to your desired window (for example, 30 or 60 days) and let the API return only the Subscriptions that need attention. Combine with the Status filter set to 1 (Enabled) to exclude already suspended Subscriptions from renewal reports.

Use enum values and GUIDs in filters, not strings

Filters are based on enum values (numbers) and GUIDs. Use the values exactly as shown in the request examples. For example, filter the status with 1 (Enabled) or 0 (Disabled); string values such as "Enabled", "Active" or "Suspended" are not supported and do not return the expected result. To get the current list of available values for each filter, call the filters endpoint (see Retrieving filter values). GUID values are not case-sensitive.

Handle empty results gracefully

A response with Total: 0 and an empty Items array is not an error — it means no Subscriptions match the given criteria. Your integration should handle this as a valid state rather than treating it as a failure. Similarly, null values for optional fields (such as CatalogMarkup, Tenant, or DistributorId) are expected and should not cause parsing errors.

Map API field names to Platform terminology

The API uses "Reseller" in its field names (ResellerId, ResellerFullName, ResellerCountryName) while the Platform UI and documentation use Seller. When building user-facing features or reports on top of this API, map these fields to their Platform equivalents to keep terminology consistent for your users. Similarly, the API returns "Enabled"/"Disabled" for status while the UI displays "Active"/"Suspended."

Summary

The POST /subscriptions/search endpoint provides a programmatic way to retrieve, search, and filter Subscriptions from the Subscription Management workspace. It supports free-text search across multiple fields, multi-field filtering with AND/OR logic using enum values and GUIDs, and expiration/Renewal windows via NDaysCount. Distributors can query their whole channel by passing DistributorId in the request body, and the available filter values can be retrieved with the dedicated filters endpoint. The response includes all data fields visible in the Seller View and Channel View grids, including Seller-specific fields for channel-wide Subscription management. For full API reference and interactive testing, visit the Search Subscriptions endpoint on the Developer Portal.

Related content

• Seller Subscription Management overview
• Channel Subscription Management overview
• Manage Subscriptions via APIs
• Reporting API v1 - overview
• Retrieve subscription search filters — Developer Portal
• Search Subscriptions — Developer Portal