> ## Documentation Index > Fetch the complete documentation index at: https://docs.paynext.com/llms.txt > Use this file to discover all available pages before exploring further. # Find subscriptions > Find subscriptions you've previously created using PayNext's Search Query Language. Don't use search in read-after-write flows where strict consistency is necessary. Under normal operating conditions, data is searchable in less than a minute. Occasionally, propagation of new or updated data can be up to an hour behind. ## Search Query Language Build a search query by combining one or more search clauses. A clause has the format `field operator value` where the operators are `:`, `~`, `>`, `<`, `>=`, `<=`, or the prefix `-` for negation. ### Operators | Operator | Description | Example | |---|---|---| | `:` | Exact match (case-insensitive) | `status:"active"` | | `~` | Substring match (min 3 chars, case-insensitive) | `plan.name~"pro"` | | `>` | Greater than | `next_billing_date>"2025-01-01T00:00:00Z"` | | `>=` | Greater than or equal | `created_at>="2025-01-01T00:00:00Z"` | | `<` | Less than | `created_at<"2025-12-31T23:59:59Z"` | | `<=` | Less than or equal | `next_billing_date<="2025-12-31T23:59:59Z"` | | `-` | Negation (prefix) | `-status:"cancelled"` | ### Logical Operators Combine clauses with `AND` or `OR`. Clauses separated by a space default to `AND` logic. You cannot mix `AND` and `OR` in the same query. Maximum of 10 clauses per query. ### Quoting String values must be enclosed in single or double quotes. Numeric values do not require quotes. Escape quotes with a backslash. ### Metadata Query metadata fields using bracket notation: `metadata["key"]:"value"`. ### Null Checks Use `field:null` to find records where a field is empty or absent. Use `-field:null` to find records where a field is present. ### Nested Fields Access nested object fields using dot notation. Examples: - `customer.email:"jane@example.com"` - `plan.type:"recurring"` - `plan.price.amount>=1999` - `past_due.attempt_count>=3` ### Searchable Subscription Fields **Top-level fields:** | Field | Type | Operators | |---|---|---| | `id` | token | `:` | | `status` | string (trial/active/past_due/cancelled/scheduled_for_cancellation) | `:` | | `created_at` | date (RFC3339) | `:`, `>`, `>=`, `<`, `<=` | | `updated_at` | date (RFC3339) | `:`, `>`, `>=`, `<`, `<=` | | `current_period_start` | date (RFC3339) | `:`, `>`, `>=`, `<`, `<=` | | `current_period_end` | date (RFC3339) | `:`, `>`, `>=`, `<`, `<=` | | `next_billing_date` | date (RFC3339) | `:`, `>`, `>=`, `<`, `<=` | | `metadata["key"]` | string | `:` | **Nested customer fields:** | Field | Type | Operators | |---|---|---| | `customer.id` | token | `:` | | `customer.email` | string | `:`, `~` | | `customer.full_name` | string | `:`, `~` | | `customer.phone` | string | `:`, `~` | | `customer.external_id` | token | `:` | | `customer.created_at` | date (RFC3339) | `:`, `>`, `>=`, `<`, `<=` | | `customer.updated_at` | date (RFC3339) | `:`, `>`, `>=`, `<`, `<=` | | `customer.metadata["key"]` | string | `:` | | `customer.address.country` | string (ISO-2) | `:` | | `customer.address.city` | string | `:`, `~` | | `customer.address.state` | string | `:` | | `customer.address.postal_code` | string | `:` | | `customer.address.line1` | string | `:`, `~` | | `customer.address.line2` | string | `:`, `~` | **Nested plan fields:** | Field | Type | Operators | |---|---|---| | `plan.id` | token | `:` | | `plan.name` | string | `:`, `~` | | `plan.type` | string (recurring/one-off) | `:` | | `plan.interval` | string (days/months/years) | `:` | | `plan.interval_count` | numeric | `:`, `>`, `>=`, `<`, `<=` | | `plan.trial_interval` | string (days/months/years) | `:` | | `plan.trial_interval_count` | numeric | `:`, `>`, `>=`, `<`, `<=` | | `plan.archived_at` | date (RFC3339, nullable) | `:`, `>`, `>=`, `<`, `<=` | | `plan.price.currency` | string (ISO 4217) | `:` | | `plan.price.amount` | numeric (minor units) | `:`, `>`, `>=`, `<`, `<=` | | `plan.trial_price.currency` | string (ISO 4217) | `:` | | `plan.trial_price.amount` | numeric (minor units) | `:`, `>`, `>=`, `<`, `<=` | | `plan.tax.collect_tax` | string (DEFAULT/COLLECT/DONT_COLLECT) | `:` | ## OpenAPI ````yaml /api-reference/openapi3-v2.0.0.json get /subscriptions openapi: 3.0.1 info: contact: {} description: Billing API title: Billing v2.0.0 version: '3.0' servers: - url: https://sandbox-api.paynext.com/ security: [] paths: /subscriptions: get: tags: - Subscriptions summary: Find subscriptions description: >- Find subscriptions you've previously created using PayNext's Search Query Language. Don't use search in read-after-write flows where strict consistency is necessary. Under normal operating conditions, data is searchable in less than a minute. Occasionally, propagation of new or updated data can be up to an hour behind. ## Search Query Language Build a search query by combining one or more search clauses. A clause has the format `field operator value` where the operators are `:`, `~`, `>`, `<`, `>=`, `<=`, or the prefix `-` for negation. ### Operators | Operator | Description | Example | |---|---|---| | `:` | Exact match (case-insensitive) | `status:"active"` | | `~` | Substring match (min 3 chars, case-insensitive) | `plan.name~"pro"` | | `>` | Greater than | `next_billing_date>"2025-01-01T00:00:00Z"` | | `>=` | Greater than or equal | `created_at>="2025-01-01T00:00:00Z"` | | `<` | Less than | `created_at<"2025-12-31T23:59:59Z"` | | `<=` | Less than or equal | `next_billing_date<="2025-12-31T23:59:59Z"` | | `-` | Negation (prefix) | `-status:"cancelled"` | ### Logical Operators Combine clauses with `AND` or `OR`. Clauses separated by a space default to `AND` logic. You cannot mix `AND` and `OR` in the same query. Maximum of 10 clauses per query. ### Quoting String values must be enclosed in single or double quotes. Numeric values do not require quotes. Escape quotes with a backslash. ### Metadata Query metadata fields using bracket notation: `metadata["key"]:"value"`. ### Null Checks Use `field:null` to find records where a field is empty or absent. Use `-field:null` to find records where a field is present. ### Nested Fields Access nested object fields using dot notation. Examples: - `customer.email:"jane@example.com"` - `plan.type:"recurring"` - `plan.price.amount>=1999` - `past_due.attempt_count>=3` ### Searchable Subscription Fields **Top-level fields:** | Field | Type | Operators | |---|---|---| | `id` | token | `:` | | `status` | string (trial/active/past_due/cancelled/scheduled_for_cancellation) | `:` | | `created_at` | date (RFC3339) | `:`, `>`, `>=`, `<`, `<=` | | `updated_at` | date (RFC3339) | `:`, `>`, `>=`, `<`, `<=` | | `current_period_start` | date (RFC3339) | `:`, `>`, `>=`, `<`, `<=` | | `current_period_end` | date (RFC3339) | `:`, `>`, `>=`, `<`, `<=` | | `next_billing_date` | date (RFC3339) | `:`, `>`, `>=`, `<`, `<=` | | `metadata["key"]` | string | `:` | **Nested customer fields:** | Field | Type | Operators | |---|---|---| | `customer.id` | token | `:` | | `customer.email` | string | `:`, `~` | | `customer.full_name` | string | `:`, `~` | | `customer.phone` | string | `:`, `~` | | `customer.external_id` | token | `:` | | `customer.created_at` | date (RFC3339) | `:`, `>`, `>=`, `<`, `<=` | | `customer.updated_at` | date (RFC3339) | `:`, `>`, `>=`, `<`, `<=` | | `customer.metadata["key"]` | string | `:` | | `customer.address.country` | string (ISO-2) | `:` | | `customer.address.city` | string | `:`, `~` | | `customer.address.state` | string | `:` | | `customer.address.postal_code` | string | `:` | | `customer.address.line1` | string | `:`, `~` | | `customer.address.line2` | string | `:`, `~` | **Nested plan fields:** | Field | Type | Operators | |---|---|---| | `plan.id` | token | `:` | | `plan.name` | string | `:`, `~` | | `plan.type` | string (recurring/one-off) | `:` | | `plan.interval` | string (days/months/years) | `:` | | `plan.interval_count` | numeric | `:`, `>`, `>=`, `<`, `<=` | | `plan.trial_interval` | string (days/months/years) | `:` | | `plan.trial_interval_count` | numeric | `:`, `>`, `>=`, `<`, `<=` | | `plan.archived_at` | date (RFC3339, nullable) | `:`, `>`, `>=`, `<`, `<=` | | `plan.price.currency` | string (ISO 4217) | `:` | | `plan.price.amount` | numeric (minor units) | `:`, `>`, `>=`, `<`, `<=` | | `plan.trial_price.currency` | string (ISO 4217) | `:` | | `plan.trial_price.amount` | numeric (minor units) | `:`, `>`, `>=`, `<`, `<=` | | `plan.tax.collect_tax` | string (DEFAULT/COLLECT/DONT_COLLECT) | `:` | operationId: findSubscriptions parameters: - description: Specifies the version of the API to use in: header name: X-API-Version schema: enum: - 2.0.0 type: string default: 2.0.0 required: true - in: query name: query required: true schema: type: string description: >- The search query string. Uses PayNext's Search Query Language. Supports exact match (`:`), substring match (`~`), numeric comparisons (`>`, `>=`, `<`, `<=`), negation (`-`), logical operators (`AND`, `OR`), and nested field access (dot notation). Field names use dotted paths (for example `payment_status`, `customer.email`, `payment_method.details.last4`); short aliases are not accepted. See the endpoint description for the full list of searchable fields and their types. Maximum 10 clauses per query. example: status:"active" AND plan.type:"recurring" - in: query name: limit schema: type: integer default: 10 minimum: 1 maximum: 100 description: >- A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10. - in: query name: page schema: type: string description: >- A cursor for pagination across multiple pages of results. Don't include this parameter on the first call. Use the next_page value returned in a previous response to request subsequent results. responses: '200': description: >- A dictionary with a data property that contains an array of up to limit subscriptions. If no subscriptions match the query, the resulting array will be empty. content: application/json: schema: $ref: '#/components/schemas/subscriptions.SearchResultDTO' '400': description: Bad Request — missing or invalid query parameter content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: subscriptions.SearchResultDTO: type: object properties: object: type: string enum: - subscriptions description: >- String representing the object's type. Value is always `subscriptions`. example: subscriptions total_count: description: >- The accurate total number of records matching the query (not capped at 10,000). Returned alongside the cursor pagination fields. example: 142 type: integer url: type: string description: The URL for accessing this list. example: /v1/subscriptions data: type: array items: $ref: >- #/components/schemas/core_model.SubscriptionResWithRelationsAndPlanDTO description: >- An array of up to limit subscriptions that match the query. Each entry in the array is a separate subscription object. If no subscriptions match the query, the resulting array will be empty. has_more: type: boolean description: >- Whether or not there are more elements available after this set. If false, this set comprises the end of the list. example: false next_page: type: string description: >- A cursor for use in pagination. If has_more is true, you can pass the value of next_page to a subsequent call to fetch the next page of results. example: null nullable: true ErrorResponse: type: object properties: error: type: object properties: type: type: string enum: - api_error - invalid_request_error - authentication_error description: The type of error returned. example: invalid_request_error code: type: string description: >- For some errors that could be handled programmatically, a short string indicating the error code reported. example: parameter_missing message: type: string description: A human-readable message providing more details about the error. example: 'Missing required parameter: email' param: type: string description: >- If the error is parameter-specific, the parameter related to the error. example: email required: - type - message core_model.SubscriptionResWithRelationsAndPlanDTO: properties: id: description: Unique identifier for the subscription example: sub_123e4567-e89b-12d3-a456-426614174000 type: string x-order: '0' current_period_end: type: string cancelled_at: description: >- UTC timestamp of when the subscription became cancelled; null unless the subscription is cancelled example: '2026-06-10T14:32:08Z' type: string cancellation_details: description: >- Server-attested cancellation attribution. Always present; sub-fields are null unless the subscription is cancelled (or scheduled for cancellation). properties: reason: description: Why the subscription was cancelled enum: - merchant_initiated - past_due_max_attempts_reached - workflow_action - fraud_prevention example: fraud_prevention type: string trigger_payment_id: description: >- Payment that triggered a system cancellation (prefixed pay_); null for merchant-initiated cancels example: pay_e8a1b2c3-1d2e-3f4a-5b6c-7d8e9f0a1b2c type: string type: object current_period_start: type: string customer: $ref: '#/components/schemas/core_model.CustomerResDTO' next_billing_date: description: Next scheduled billing date for the subscription example: '2025-06-26T12:00:00Z' type: string past_due: allOf: - $ref: '#/components/schemas/core_model.SubscriptionPastDueAttemptsInfo' description: Information about past due attempts type: object plan: $ref: '#/components/schemas/core_model.PlanCustomerResDTO' status: description: Current status of the subscription enum: - trial - active - past_due - cancelled - scheduled_for_cancellation type: string metadata: additionalProperties: type: string description: |- Custom metadata associated with the subscription A dictionary of key-value pairs. example: key: value type: object created_at: description: >- The date and time at which the subscription was created in UTC format example: '2025-05-26T10:00:00Z' type: string x-order: '1' updated_at: description: The date and time of the last subscription update in UTC format example: '2025-05-27T10:00:00Z' type: string x-order: '2' type: object core_model.CustomerResDTO: properties: id: description: Unique identifier example: cus_b8d0fe7e-3a7f-4b5f-a68b-d31358b49c3f type: string x-order: '0' address: allOf: - $ref: '#/components/schemas/core_model.BillingAddress' description: Address associated with customer type: object x-order: '3' email: description: Email of the customer example: alice.johnson@example.com type: string x-order: '4' external_id: description: External ID of the customer example: ext_001 type: string x-order: '5' full_name: description: Full name of the customer example: Alice Johnson type: string x-order: '7' phone: description: Customer's phone number example: +1-555-123-4567 type: string x-order: '8' metadata: additionalProperties: type: string description: Additional metadata as a JSON object example: key: value type: object x-order: '6' created_at: description: The date and time the customer was created in UTC format example: '2025-05-28T14:00:00Z' type: string x-order: '1' updated_at: description: The date and time the customer was last updated in UTC format example: '2025-05-28T14:05:00Z' type: string x-order: '2' type: object core_model.SubscriptionPastDueAttemptsInfo: properties: attempt_count: description: Number of current attempts count example: 2 type: integer max_attempts_count: description: Maximum count of attempts example: 7 type: integer type: object core_model.PlanCustomerResDTO: properties: id: description: Unique identifier for the plan example: price_1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d type: string x-order: '0' archived_at: description: The date and time at which the plan was archived in UTC format example: '2025-06-01T10:00:00Z' type: string interval: description: Type of the billing period enum: - days - months - years example: days type: string x-order: '4' interval_count: description: Number of billing periods per cycle example: 1 type: integer x-order: '5' name: description: Display name of the plan example: Pro Plan type: string x-order: '2' price: allOf: - $ref: '#/components/schemas/core_model.PlanPrice' description: Pricing details for the plan type: object x-order: '6' tax: allOf: - $ref: '#/components/schemas/core_model.PlanTax' description: Tax info type: object x-order: '10' trial_interval: description: Type of trial period enum: - days - months - years example: days type: string x-order: '7' trial_interval_count: description: Length of the trial period example: 14 type: integer x-order: '8' trial_price: allOf: - $ref: '#/components/schemas/core_model.PlanPrice' description: Trial pricing details type: object x-order: '9' type: description: Type of the plan enum: - recurring - one-off example: recurring type: string x-order: '3' type: object core_model.BillingAddress: properties: city: example: San Francisco type: string country: enum: - AD - AE - AF - AG - AL - AM - AO - AR - AS - AT - AU - AW - AX - AZ - BA - BB - BD - BE - BF - BG - BH - BI - BJ - BL - BM - BN - BO - BQ - BR - BS - BT - BW - BY - BZ - CA - CD - CF - CG - CH - CI - CL - CM - CN - CO - CR - CU - CU-P - CV - CW - CY - CZ - DE - DJ - DK - DM - DO - DZ - EC - EE - EG - ER - ES - ET - FI - FJ - FK - FM - FR - GA - GB - GD - GE - GF - GG - GH - GI - GL - GM - GN - GP - GQ - GR - GT - GU - GW - GY - HK - HN - HR - HT - HU - ID - IE - IL - IM - IN - IQ - IR - IS - IT - JE - JM - JO - JP - KE - KG - KH - KI - KM - KN - KP - KR - KW - KY - KZ - LA - LB - LC - LI - LK - LR - LS - LT - LU - LV - LY - MA - MC - MD - ME - MF - MG - MH - MK - ML - MM - MN - MO - MP - MQ - MR - MS - MT - MU - MV - MW - MX - MY - MZ - NA - NC - NE - NG - NI - NL - 'NO' - NP - NR - NU - NZ - OM - PA - PE - PF - PG - PH - PK - PL - PM - PN - PR - PS - PT - PW - PY - QA - RE - RO - RS - RU - RW - SA - SB - SC - SD - SE - SG - SH - SI - SK - SL - SM - SN - SO - SR - SS - ST - SV - SX - SY - SZ - TC - TD - TG - TH - TJ - TK - TL - TM - TN - TO - TR - TT - TV - TW - TZ - UA - UG - US - UY - UZ - VA - VC - VE - VG - VI - VN - VU - WF - WS - XK - YE - YT - ZA - ZM - ZW type: string line1: example: 123 Market Street type: string line2: example: Suite 400 type: string postal_code: example: '94105' type: string state: example: CA type: string type: object core_model.PlanPrice: properties: amount: description: Price amount in minor units example: 1999 type: integer currency: description: >- The 3-letter currency code in ISO 4217 format. e.g. use USD for US dollars enum: - AED - AFN - ALL - AMD - AOA - ARS - AUD - AWG - AZN - BAM - BBD - BDT - BGN - BHD - BIF - BMD - BND - BOB - BRL - BSD - BTN - BWP - BYN - BZD - CAD - CDF - CHF - CLP - CNY - COP - CRC - CUC - CUP - CVE - CZK - DJF - DKK - DOP - DZD - EGP - ERN - ETB - EUR - FJD - FKP - GBP - GEL - GHS - GIP - GMD - GNF - GTQ - GYD - HKD - HNL - HTG - HUF - IDR - ILS - IMP - INR - IQD - IRR - ISK - JEP - JMD - JOD - JPY - KES - KGS - KHR - KMF - KPW - KRW - KWD - KYD - KZT - LAK - LBP - LKR - LRD - LSL - LYD - MAD - MDL - MGA - MKD - MMK - MNT - MOP - MRU - MUR - MVR - MWK - MXN - MYR - MZN - NAD - NGN - NIO - NOK - NPR - NZD - OMR - PAB - PEN - PGK - PHP - PKR - PLN - PYG - QAR - RON - RSD - RUB - RWF - SAR - SBD - SCR - SDG - SEK - SGD - SHP - SLE - SOS - SRD - SSP - STD - STN - SVC - SYP - SZL - THB - TJS - TMT - TND - TOP - TRY - TTD - TWD - TZS - BOV - COU - CHE - CHW - MXV - UGX - VES - VND - VUV - XAF - XCD - XCG - XOF - XPF - YER - USD example: AED type: string type: object core_model.PlanTax: properties: collect_tax: allOf: - $ref: '#/components/schemas/core_model.PlanTaxCollection' example: DEFAULT type: object type: object core_model.PlanTaxCollection: enum: - DEFAULT - COLLECT - DONT_COLLECT type: string x-enum-varnames: - PlanTaxCollectionDEFAULT - PlanTaxCollectionCOLLECT - PlanTaxCollectionDONTCOLLECT ````