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 Vendor, status, Customer, Offer, Markup, pricing source, scheduled actions, Renewal configuration, Quantity, distribution tier, and more.
• 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. 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

Request body parameters

Available filter fields

The following fields can be used in the Filters array. Each filter object specifies a Field name and an array of accepted values.

Request examples

Example 1 — Single filter by Vendor

This request retrieves page 1 with 20 results, filtering Subscriptions by two specific Vendors, with an expiration/Renewal window of 30 days.

{
    "Page": 1,
    "PageSize": 20,
    "Query": "",
    "Filters": [
        {
            "Field": "VendorId",
            "Filters": [
                "a1b2c3d4-e5f6-7890-abcd-111111111111",
                "a1b2c3d4-e5f6-7890-abcd-222222222222"
            ]
        }
    ],
    "NDaysCount": 30
}

Example 2 — Multiple filters combined (Vendor + Status + Tier)

This request combines three filters: only active Subscriptions, from a specific Vendor, sold through the Direct Model. All three conditions must be met (AND logic).

{
    "Page": 1,
    "PageSize": 20,
    "Query": "",
    "Filters": [
        {
            "Field": "VendorId",
            "Filters": ["a1b2c3d4-e5f6-7890-abcd-111111111111"]
        },
        {
            "Field": "Status",
            "Filters": ["Enabled"]
        },
        {
            "Field": "SubscriptionTier",
            "Filters": ["Direct"]
        }
    ]
}

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 of a specific Customer that are expiring or auto-renewing within 60 days.

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

Example 5 — Channel View: filter by Seller

This request filters Subscriptions managed by a specific Seller 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.

{
    "Page": 1,
    "PageSize": 20,
    "Query": "",
    "Filters": [
        {
            "Field": "ResellerId",
            "Filters": ["c3d4e5f6-a7b8-9012-cdef-444444444444"]
        },
        {
            "Field": "Status",
            "Filters": ["Enabled"]
        }
    ]
}

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. Start with a reasonable PageSize (for example, 20–50) and use the Total value in the response to calculate how many pages you need to iterate through. Requesting very large page sizes can lead to slow response times and timeouts.

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 + VendorId + SubscriptionTier) 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 Vendor 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 "Enabled" to exclude already suspended Subscriptions from renewal reports.

Respect case sensitivity in filter values

All filter values are case-sensitive. For example, "Enabled" will work but "enabled" will not. When building integrations, make sure to use exact values as documented in the Available filter fields table. GUID values are not case-sensitive, but string values such as Status, SubscriptionTier, and PriceSource must match exactly.

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 uses "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, and expiration/Renewal windows via NDaysCount. 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
• Search Subscriptions — Developer Portal