> ## 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.

# Search

> Look up objects in your PayNext data using a flexible query language.

Some top-level API resources support retrieval with search API methods. You can use the search APIs to retrieve your PayNext objects in a flexible manner. Using search is a faster alternative to paginating through all resources with individual filter parameters.

Search is available on the list endpoints — `GET /payments`, `GET /customers`, `GET /subscriptions`, and `GET /plans` — when you set the `X-API-Version: 2.0.0` header. With this header, the endpoint parses the DSL from the `query` parameter, ignores the legacy filter query parameters, and returns the search envelope (`object`, `url`, `has_more`, `next_page`, `total_count`, `data`). Without the header, the endpoints keep their v1.x behavior and response shape. See [Parameters](#parameters) and [Response format](#response-format) below.

To create a search query, review the [search query language](#search-query-language) and reference the query fields of the resource:

* [Query fields for Payments](#query-fields-for-payments)
* [Query fields for Customers](#query-fields-for-customers)
* [Query fields for Subscriptions](#query-fields-for-subscriptions)
* [Query fields for Plans](#query-fields-for-plans)

<Note>
  Field names use **dotted paths** (for example `payment_status`, `customer.email`, `payment_method.details.last4`). Short aliases such as `status`, `email`, or `card_last4` are **not** accepted and return an error. Always use the exact field names listed in the tables below.
</Note>

## Examples

Here are some examples of what you can do with the search APIs.

### Payments metadata search

Look up payments matching a custom metadata value.

```bash curl theme={"system"}
curl -G https://api.paynext.com/payments \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-API-Version: 2.0.0" \
  --data-urlencode "query=metadata['order_id']:'ord_abc123'"
```

### Payments by status and amount

Look up settled payments over a specific amount.

```bash curl theme={"system"}
curl -G https://api.paynext.com/payments \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-API-Version: 2.0.0" \
  --data-urlencode "query=payment_status:'SETTLED' AND amount>=10000"
```

### Customers email search

Look up customers matching an email substring.

```bash curl theme={"system"}
curl -G https://api.paynext.com/customers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-API-Version: 2.0.0" \
  --data-urlencode "query=email~'alice'"
```

### Negation filter

Look up payments not in USD currency.

```bash curl theme={"system"}
curl -G https://api.paynext.com/payments \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-API-Version: 2.0.0" \
  --data-urlencode "query=-currency_code:'USD'"
```

### Numeric filter

Filter payments with an amount greater than 10000.

```bash curl theme={"system"}
curl -G https://api.paynext.com/payments \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-API-Version: 2.0.0" \
  -d "query=amount>10000"
```

### Combining multiple filters

Look up payments matching a combination of metadata and currency.

```bash curl theme={"system"}
curl -G https://api.paynext.com/payments \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-API-Version: 2.0.0" \
  --data-urlencode "query=metadata['campaign']:'summer_sale' AND currency_code:'USD'"
```

***

## Search query language

### Query structure and terminology

A query `clause` consists of a `field` followed by an `operator` followed by a `value`:

|          |                                      |
| -------- | ------------------------------------ |
| clause   | `customer.email:"alice@example.com"` |
| field    | `customer.email`                     |
| operator | `:`                                  |
| value    | `alice@example.com`                  |

You can combine up to **10 query clauses** in a search by either separating them with a space, or using the `AND` or `OR` keywords (case insensitive). You cannot combine `AND` and `OR` in the same query. There is no option to use parentheses to give priority to certain logic operators. By default, the API combines clauses with `AND` logic. On the Payments and Customers endpoints, all clauses in an `OR` query must target the same field; the Subscriptions and Plans endpoints allow `OR` across different fields.

The example query `customer.email:"alice@example.com" metadata["tier"]:"premium"` matches records where both the customer email is [alice@example.com](mailto:alice@example.com) and the metadata includes `tier` with a value of `premium`.

### Negation

You can negate query clauses using a `-` character. For example, the following search returns records that don't match the currency USD:

`-currency_code:"USD"`

### Field types, substring matching, and numeric comparators

Each field has a type that defines the operations you can use on it. For a full list of available fields and their types, see [supported query fields for each resource](#supported-query-fields-for-each-resource).

Using an unsupported operator — such as specifying greater than (`>`) on a token field — returns an error.

| Type    | Operators                                                                                                                                                                              |
| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| token   | exact match with `:` (case insensitive)                                                                                                                                                |
| string  | exact match with `:`, substring match with `~` (case insensitive). An exact match on a string type returns any record that contains all of the words from the query in the same order. |
| numeric | exact match with `:`, greater than / less than with `>`, `<`, `>=`, `<=`                                                                                                               |
| date    | exact match with `:`, range with `>`, `<`, `>=`, `<=`. Accepts Unix seconds (e.g. `1620310503`) or an RFC3339 timestamp (e.g. `2025-05-25T14:30:00Z`)                                  |
| boolean | exact match with `:` against `true` / `false`                                                                                                                                          |

### Quotes

You must use quotation marks around string values. Quotation marks are optional for numeric values. For example:

* `currency_code:"USD"` — quotes are required
* `amount:1000` — quotes are optional

You can escape quotes inside of quotes with a backslash (`\`):

`statement_descriptor:"the descriptor called \"My Store\""`

### Metadata

You can perform searches on metadata that you've added to objects that support it.

Use either bracket or dotted syntax to construct a clause for a metadata search: `metadata["<field>"]:"<value>"` or `metadata.<field>:"<value>"`. The metadata key must consist of `[a-zA-Z0-9_]` characters.

The following clause demonstrates how to query for records with an order ID of `ord_abc123`:

`metadata["order_id"]:"ord_abc123"`

You can query for the presence of a metadata key on an object. The following clause matches all records where `order_id` is a metadata key:

`-metadata["order_id"]:null`

Some resources also expose scoped metadata fields for related objects — for example `customer.metadata["<key>"]` on payments and subscriptions, or `plan.metadata["<key>"]` on subscriptions. These are listed in each resource's field tables.

### Null operator

The `null` keyword checks for field presence or absence:

| Query                  | Meaning                          |
| ---------------------- | -------------------------------- |
| `customer.phone:null`  | Field is empty or not set        |
| `-customer.phone:null` | Field is present and has a value |

`:null` is supported on token, string, and date fields. It is not supported on numeric fields.

### Search syntax

The following table lists the syntax that you can use to construct a query.

| Syntax               | Usage                           | Description                                                                                                       | Examples                                                                                 |
| -------------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `:`                  | `field:value`                   | Exact match operator (case insensitive)                                                                           | `currency_code:"EUR"` returns records where the currency is exactly EUR                  |
| `AND`, `and`         | `field:value1 AND field:value2` | Both clauses must match (case insensitive)                                                                        | `payment_status:"SETTLED" AND amount:500`                                                |
| `OR`, `or`           | `field:value1 OR field:value2`  | Either clause matches (case insensitive). On Payments and Customers, all `OR` clauses must target the same field. | `currency_code:"USD" OR currency_code:"EUR"`                                             |
| `-`                  | `-field:value`                  | Returns records that don't match the clause                                                                       | `-currency_code:"JPY"` returns records not in JPY                                        |
| `NULL`, `null`       | `field:null`                    | A special token used for field presence (case insensitive)                                                        | `customer.phone:null` returns records where phone is empty                               |
| `\`                  | `"\"\"`                         | Escape quotes within quotes                                                                                       | `statement_descriptor:"called \"My Store\""`                                             |
| `~`                  | `field~value`                   | Substring match operator (minimum 3 characters)                                                                   | `customer.email~"ali"` returns matches for [alice@example.com](mailto:alice@example.com) |
| `>`, `<`, `>=`, `<=` | `field>value`, `field>=value`   | Greater than/less than operators                                                                                  | `amount>=1000` returns objects with amount 1000 or greater                               |

***

## Supported query fields for each resource

### Query fields for Payments

#### Core

| Field                  | Usage                               | Type    |
| ---------------------- | ----------------------------------- | ------- |
| `id`                   | `id:"pay_e8a1..."`                  | token   |
| `payment_status`       | `payment_status:"SETTLED"`          | token   |
| `payment_type`         | `payment_type:"CIT"`                | token   |
| `transaction_type`     | `transaction_type:"Auth"`           | token   |
| `currency_code`        | `currency_code:"USD"`               | token   |
| `amount`               | `amount>1000`                       | numeric |
| `amount_usd`           | `amount_usd>=5000`                  | numeric |
| `statement_descriptor` | `statement_descriptor~"MY COMPANY"` | string  |
| `created_at`           | `created_at>1620310503`             | date    |
| `updated_at`           | `updated_at>1620310503`             | date    |

#### Customer

| Field                          | Usage                                  | Type   |
| ------------------------------ | -------------------------------------- | ------ |
| `customer.id`                  | `customer.id:"cus_a1b2..."`            | token  |
| `customer.email`               | `customer.email~"alice"`               | string |
| `customer.full_name`           | `customer.full_name~"John"`            | string |
| `customer.phone`               | `customer.phone:"+15551234567"`        | string |
| `customer.external_id`         | `customer.external_id:"ord_001"`       | string |
| `customer.created_at`          | `customer.created_at>1620310503`       | date   |
| `customer.updated_at`          | `customer.updated_at>1620310503`       | date   |
| `customer.address.country`     | `customer.address.country:"US"`        | token  |
| `customer.address.state`       | `customer.address.state:"CA"`          | token  |
| `customer.address.postal_code` | `customer.address.postal_code:"94105"` | token  |
| `customer.address.city`        | `customer.address.city~"Francisco"`    | string |
| `customer.address.line1`       | `customer.address.line1~"Market"`      | string |
| `customer.address.line2`       | `customer.address.line2~"Suite"`       | string |

#### Subscription

| Field                               | Usage                                          | Type  |
| ----------------------------------- | ---------------------------------------------- | ----- |
| `subscription.id`                   | `subscription.id:"sub_d1e2..."`                | token |
| `subscription.status`               | `subscription.status:"active"`                 | token |
| `subscription.created_at`           | `subscription.created_at>1620310503`           | date  |
| `subscription.updated_at`           | `subscription.updated_at>1620310503`           | date  |
| `subscription.current_period_start` | `subscription.current_period_start>1620310503` | date  |
| `subscription.current_period_end`   | `subscription.current_period_end<1620310503`   | date  |
| `subscription.next_billing_date`    | `subscription.next_billing_date>1620310503`    | date  |

#### Processor

| Field            | Usage                        | Type  |
| ---------------- | ---------------------------- | ----- |
| `processor.id`   | `processor.id:"prc_f1a2..."` | token |
| `processor.type` | `processor.type:"stripe"`    | token |

#### Payment method and card

| Field                                     | Usage                                              | Type    |
| ----------------------------------------- | -------------------------------------------------- | ------- |
| `payment_method.type`                     | `payment_method.type:"CARD"`                       | token   |
| `payment_method.details.bin`              | `payment_method.details.bin:"411111"`              | token   |
| `payment_method.details.last4`            | `payment_method.details.last4:"4242"`              | token   |
| `payment_method.details.exp_month`        | `payment_method.details.exp_month:12`              | numeric |
| `payment_method.details.exp_year`         | `payment_method.details.exp_year:2028`             | numeric |
| `payment_method.details.bin_data.brand`   | `payment_method.details.bin_data.brand:"visa"`     | token   |
| `payment_method.details.bin_data.country` | `payment_method.details.bin_data.country:"US"`     | token   |
| `payment_method.details.bin_data.funding` | `payment_method.details.bin_data.funding:"credit"` | token   |
| `payment_method.details.bin_data.issuer`  | `payment_method.details.bin_data.issuer~"Chase"`   | string  |

#### Network token

| Field                                               | Usage                                                     | Type    |
| --------------------------------------------------- | --------------------------------------------------------- | ------- |
| `payment_method.details.token`                      | `payment_method.details.token:"tok_..."`                  | token   |
| `payment_method.details.token_service_provider`     | `payment_method.details.token_service_provider:"visa"`    | token   |
| `payment_method.details.token_exp_month`            | `payment_method.details.token_exp_month:12`               | numeric |
| `payment_method.details.token_exp_year`             | `payment_method.details.token_exp_year:2028`              | numeric |
| `payment_method.details.network_token.bin`          | `payment_method.details.network_token.bin:"411111"`       | token   |
| `payment_method.details.network_token.last4`        | `payment_method.details.network_token.last4:"4242"`       | token   |
| `payment_method.details.network_token.expiry_month` | `payment_method.details.network_token.expiry_month:"12"`  | token   |
| `payment_method.details.network_token.expiry_year`  | `payment_method.details.network_token.expiry_year:"2028"` | token   |

#### PayPal payer info

| Field                                          | Usage                                                  | Type   |
| ---------------------------------------------- | ------------------------------------------------------ | ------ |
| `payment_method.details.payer_info.email`      | `payment_method.details.payer_info.email~"alice"`      | string |
| `payment_method.details.payer_info.first_name` | `payment_method.details.payer_info.first_name~"Jane"`  | string |
| `payment_method.details.payer_info.last_name`  | `payment_method.details.payer_info.last_name~"Doe"`    | string |
| `payment_method.details.payer_info.payer_id`   | `payment_method.details.payer_info.payer_id:"1234567"` | token  |

#### Processor customer

| Field                                                | Usage                                                            | Type   |
| ---------------------------------------------------- | ---------------------------------------------------------------- | ------ |
| `payment_method.details.processor_customer_email`    | `payment_method.details.processor_customer_email~"alice"`        | string |
| `payment_method.details.processor_customer_id`       | `payment_method.details.processor_customer_id:"cus_Stripe1"`     | token  |
| `payment_method.details.processor_payment_method_id` | `payment_method.details.processor_payment_method_id:"pm_1Nx..."` | token  |

#### Refund

| Field                | Usage                       | Type    |
| -------------------- | --------------------------- | ------- |
| `refund.is_refunded` | `refund.is_refunded:"true"` | boolean |
| `refund.status`      | `refund.status:"REFUNDED"`  | token   |
| `refund.amount`      | `refund.amount>0`           | numeric |

#### Tax

| Field               | Usage                                     | Type  |
| ------------------- | ----------------------------------------- | ----- |
| `tax.status`        | `tax.status:"calculated"`                 | token |
| `tax.behavior`      | `tax.behavior:"EXCLUSIVE"`                | token |
| `tax.error.code`    | `tax.error.code:"calculation_failed"`     | token |
| `tax.error.message` | `tax.error.message:"invalid postal code"` | token |

#### 3-D Secure

| Field                            | Usage                                              | Type    |
| -------------------------------- | -------------------------------------------------- | ------- |
| `three_d_secure.attempted`       | `three_d_secure.attempted:"true"`                  | boolean |
| `three_d_secure.flow`            | `three_d_secure.flow:"challenge"`                  | token   |
| `three_d_secure.status`          | `three_d_secure.status:"authenticated"`            | token   |
| `three_d_secure.status_reason`   | `three_d_secure.status_reason:"card_not_enrolled"` | token   |
| `three_d_secure.liability_shift` | `three_d_secure.liability_shift:"true"`            | token   |
| `three_d_secure.eci_value`       | `three_d_secure.eci_value:"05"`                    | token   |
| `three_d_secure.eci_result`      | `three_d_secure.eci_result:"authenticated"`        | token   |

#### Decline information

| Field                        | Usage                                             | Type   |
| ---------------------------- | ------------------------------------------------- | ------ |
| `status_reason.status`       | `status_reason.status:"declined"`                 | token  |
| `status_reason.decline_code` | `status_reason.decline_code:"insufficient_funds"` | token  |
| `status_reason.message`      | `status_reason.message~"expired"`                 | string |

#### AVS / CVC checks

| Field                             | Usage                                     | Type  |
| --------------------------------- | ----------------------------------------- | ----- |
| `avs_check.result.postal_code`    | `avs_check.result.postal_code:"match"`    | token |
| `avs_check.result.street_address` | `avs_check.result.street_address:"match"` | token |
| `cvc_check.result.cvc`            | `cvc_check.result.cvc:"match"`            | token |

#### Processor identifiers

| Field                                      | Usage                                                  | Type   |
| ------------------------------------------ | ------------------------------------------------------ | ------ |
| `payment_details.auth_code`                | `payment_details.auth_code:"A1B2C3"`                   | token  |
| `payment_details.processor_transaction_id` | `payment_details.processor_transaction_id:"ch_3Nx..."` | token  |
| `payment_details.network_payment_id`       | `payment_details.network_payment_id~"MCC1234"`         | string |
| `payment_details.arn`                      | `payment_details.arn:"74512345678901234567890"`        | token  |

#### Fraud prevention

| Field                                               | Usage                                                         | Type             |
| --------------------------------------------------- | ------------------------------------------------------------- | ---------------- |
| `fraud_prevention`                                  | `-fraud_prevention:null`                                      | token (presence) |
| `fraud_prevention.visa_order_insight.type`          | `fraud_prevention.visa_order_insight.type:"OI"`               | token            |
| `fraud_prevention.visa_compelling_evidence.status`  | `fraud_prevention.visa_compelling_evidence.status:"accepted"` | token            |
| `fraud_prevention.visa_rdr.status`                  | `fraud_prevention.visa_rdr.status:"accepted"`                 | token            |
| `fraud_prevention.visa_rdr.reason.code`             | `fraud_prevention.visa_rdr.reason.code:"10.4"`                | token            |
| `fraud_prevention.visa_rdr.reason.name`             | `fraud_prevention.visa_rdr.reason.name:"..."`                 | token            |
| `fraud_prevention.visa_rdr.reason.category`         | `fraud_prevention.visa_rdr.reason.category:"fraud"`           | token            |
| `fraud_prevention.mastercard_consumer_clarity.type` | `fraud_prevention.mastercard_consumer_clarity.type:"DIGITAL"` | token            |

#### Metadata

| Field                            | Usage                                       | Type  |
| -------------------------------- | ------------------------------------------- | ----- |
| `metadata["<key>"]`              | `metadata["order_id"]:"ord_123"`            | token |
| `customer.metadata["<key>"]`     | `customer.metadata["tier"]:"premium"`       | token |
| `subscription.metadata["<key>"]` | `subscription.metadata["plan_tier"]:"gold"` | token |

<Info>
  The `payment_status` field accepts the following values: `PENDING`, `FAILED`, `AUTHORIZED`, `SETTLING`, `SETTLED`, `DECLINED`, `BLOCKED`, `CANCELLED`.
</Info>

<Info>
  The `payment_method.type` field accepts values like `CARD`, `PIX`, `PAYPAL`, `CASHAPP`, `APPLEPAY`, `GOOGLEPAY`, `VENMO`, `AMAZONPAY`.
</Info>

<Info>
  The `payment_token_type` field accepts: `CARD_PAN`, `NETWORK_TOKEN`, `PROCESSOR_TOKEN`.
</Info>

<Info>
  `payment_method.details.bin_data.brand` is the card network (for example `visa`, `mastercard`). `payment_details.network_payment_id` is the scheme-side network transaction identifier returned by the processor (for example, the Mastercard trace id or Visa transaction id) — they are different fields.
</Info>

<Info>
  `customer.email` and `customer.external_id` on payments match against the customer associated with the payment.
</Info>

### Query fields for Customers

#### Core

| Field              | Usage                         | Type    |
| ------------------ | ----------------------------- | ------- |
| `id`               | `id:"cus_b8d0..."`            | token   |
| `email`            | `email~"alice"`               | string  |
| `full_name`        | `full_name~"John"`            | string  |
| `phone`            | `phone:"+15551234567"`        | string  |
| `external_id`      | `external_id:"ext_001"`       | token   |
| `created_at`       | `created_at>1620310503`       | date    |
| `updated_at`       | `updated_at>1620310503`       | date    |
| `total_spend`      | `total_spend>10000`           | numeric |
| `first_payment_at` | `first_payment_at>1620310503` | date    |
| `last_payment_at`  | `last_payment_at>1620310503`  | date    |

#### Address

| Field                 | Usage                         | Type   |
| --------------------- | ----------------------------- | ------ |
| `address.country`     | `address.country:"US"`        | token  |
| `address.state`       | `address.state:"CA"`          | token  |
| `address.postal_code` | `address.postal_code:"94105"` | token  |
| `address.city`        | `address.city~"Francisco"`    | string |
| `address.line1`       | `address.line1~"Market"`      | string |
| `address.line2`       | `address.line2~"Suite"`       | string |

#### Payment methods

| Field                                                 | Usage                                                             | Type    |
| ----------------------------------------------------- | ----------------------------------------------------------------- | ------- |
| `payment_methods.type`                                | `payment_methods.type:"CARD"`                                     | token   |
| `payment_methods.details.bin`                         | `payment_methods.details.bin:"411111"`                            | token   |
| `payment_methods.details.last4`                       | `payment_methods.details.last4:"4242"`                            | token   |
| `payment_methods.details.exp_month`                   | `payment_methods.details.exp_month:12`                            | numeric |
| `payment_methods.details.exp_year`                    | `payment_methods.details.exp_year:2028`                           | numeric |
| `payment_methods.details.token_exp_month`             | `payment_methods.details.token_exp_month:12`                      | numeric |
| `payment_methods.details.token_exp_year`              | `payment_methods.details.token_exp_year:2028`                     | numeric |
| `payment_methods.details.bin_data.brand`              | `payment_methods.details.bin_data.brand:"visa"`                   | token   |
| `payment_methods.details.bin_data.country`            | `payment_methods.details.bin_data.country:"US"`                   | token   |
| `payment_methods.details.bin_data.funding`            | `payment_methods.details.bin_data.funding:"credit"`               | token   |
| `payment_methods.details.bin_data.currency_code`      | `payment_methods.details.bin_data.currency_code:"USD"`            | token   |
| `payment_methods.details.bin_data.issuer`             | `payment_methods.details.bin_data.issuer~"Chase"`                 | string  |
| `payment_methods.details.payer_info.email`            | `payment_methods.details.payer_info.email~"alice"`                | string  |
| `payment_methods.details.payer_info.first_name`       | `payment_methods.details.payer_info.first_name~"Jane"`            | string  |
| `payment_methods.details.payer_info.last_name`        | `payment_methods.details.payer_info.last_name~"Doe"`              | string  |
| `payment_methods.details.payer_info.payer_id`         | `payment_methods.details.payer_info.payer_id:"1234567"`           | token   |
| `payment_methods.details.processor_customer_email`    | `payment_methods.details.processor_customer_email~"alice"`        | string  |
| `payment_methods.details.processor_customer_id`       | `payment_methods.details.processor_customer_id:"cus_Stripe1"`     | token   |
| `payment_methods.details.processor_payment_method_id` | `payment_methods.details.processor_payment_method_id:"pm_1Nx..."` | token   |
| `payment_methods.details.token`                       | `payment_methods.details.token:"tok_..."`                         | token   |
| `payment_methods.details.token_service_provider`      | `payment_methods.details.token_service_provider:"visa"`           | token   |
| `payment_methods.details.network_token.bin`           | `payment_methods.details.network_token.bin:"411111"`              | token   |
| `payment_methods.details.network_token.last4`         | `payment_methods.details.network_token.last4:"4242"`              | token   |
| `payment_methods.details.network_token.expiry_month`  | `payment_methods.details.network_token.expiry_month:"12"`         | token   |
| `payment_methods.details.network_token.expiry_year`   | `payment_methods.details.network_token.expiry_year:"2028"`        | token   |

#### Subscriptions

| Field                                | Usage                                           | Type  |
| ------------------------------------ | ----------------------------------------------- | ----- |
| `subscriptions.id`                   | `subscriptions.id:"sub_d1e2..."`                | token |
| `subscriptions.status`               | `subscriptions.status:"ACTIVE"`                 | token |
| `subscriptions.created_at`           | `subscriptions.created_at>1620310503`           | date  |
| `subscriptions.updated_at`           | `subscriptions.updated_at>1620310503`           | date  |
| `subscriptions.current_period_start` | `subscriptions.current_period_start>1620310503` | date  |
| `subscriptions.current_period_end`   | `subscriptions.current_period_end<1620310503`   | date  |
| `subscriptions.next_billing_date`    | `subscriptions.next_billing_date>1620310503`    | date  |

#### Subscription plan

| Field                                     | Usage                                           | Type    |
| ----------------------------------------- | ----------------------------------------------- | ------- |
| `subscriptions.plan.id`                   | `subscriptions.plan.id:"price_a5b8..."`         | token   |
| `subscriptions.plan.name`                 | `subscriptions.plan.name~"Pro"`                 | string  |
| `subscriptions.plan.type`                 | `subscriptions.plan.type:"recurring"`           | token   |
| `subscriptions.plan.interval`             | `subscriptions.plan.interval:"months"`          | token   |
| `subscriptions.plan.interval_count`       | `subscriptions.plan.interval_count:1`           | numeric |
| `subscriptions.plan.trial_interval`       | `subscriptions.plan.trial_interval:"days"`      | token   |
| `subscriptions.plan.trial_interval_count` | `subscriptions.plan.trial_interval_count:14`    | numeric |
| `subscriptions.plan.archived_at`          | `subscriptions.plan.archived_at:null`           | date    |
| `subscriptions.plan.price.currency`       | `subscriptions.plan.price.currency:"USD"`       | token   |
| `subscriptions.plan.price.amount`         | `subscriptions.plan.price.amount>1000`          | numeric |
| `subscriptions.plan.trial_price.currency` | `subscriptions.plan.trial_price.currency:"USD"` | token   |
| `subscriptions.plan.trial_price.amount`   | `subscriptions.plan.trial_price.amount:0`       | numeric |
| `subscriptions.plan.tax.collect_tax`      | `subscriptions.plan.tax.collect_tax:"true"`     | token   |

#### Metadata

| Field                             | Usage                                        | Type  |
| --------------------------------- | -------------------------------------------- | ----- |
| `metadata["<key>"]`               | `metadata["tier"]:"enterprise"`              | token |
| `customer.metadata["<key>"]`      | `customer.metadata["tier"]:"enterprise"`     | token |
| `subscriptions.metadata["<key>"]` | `subscriptions.metadata["plan_tier"]:"gold"` | token |

<Info>
  The `subscriptions.status` field accepts values like `ACTIVE`, `CANCELLED`, `PAST_DUE`, `PAUSED`, `TRIAL`, `SCHEDULED_FOR_CANCELLATION`.
</Info>

### Query fields for Subscriptions

#### Core

| Field                  | Usage                             | Type  |
| ---------------------- | --------------------------------- | ----- |
| `id`                   | `id:"sub_d1e2..."`                | token |
| `status`               | `status:"active"`                 | token |
| `created_at`           | `created_at>1620310503`           | date  |
| `updated_at`           | `updated_at>1620310503`           | date  |
| `current_period_start` | `current_period_start>1620310503` | date  |
| `current_period_end`   | `current_period_end<1620310503`   | date  |
| `next_billing_date`    | `next_billing_date>1620310503`    | date  |

#### Customer

| Field                          | Usage                                  | Type   |
| ------------------------------ | -------------------------------------- | ------ |
| `customer.id`                  | `customer.id:"cus_a1b2..."`            | token  |
| `customer.email`               | `customer.email~"alice"`               | string |
| `customer.full_name`           | `customer.full_name~"John"`            | string |
| `customer.phone`               | `customer.phone:"+15551234567"`        | string |
| `customer.external_id`         | `customer.external_id:"ext_001"`       | token  |
| `customer.created_at`          | `customer.created_at>1620310503`       | date   |
| `customer.updated_at`          | `customer.updated_at>1620310503`       | date   |
| `customer.address.country`     | `customer.address.country:"US"`        | token  |
| `customer.address.state`       | `customer.address.state:"CA"`          | token  |
| `customer.address.postal_code` | `customer.address.postal_code:"94105"` | token  |
| `customer.address.city`        | `customer.address.city~"Francisco"`    | string |
| `customer.address.line1`       | `customer.address.line1~"Market"`      | string |
| `customer.address.line2`       | `customer.address.line2~"Suite"`       | string |

#### Plan

| Field                       | Usage                             | Type    |
| --------------------------- | --------------------------------- | ------- |
| `plan.id`                   | `plan.id:"price_a5b8..."`         | token   |
| `plan.name`                 | `plan.name~"Pro"`                 | string  |
| `plan.type`                 | `plan.type:"recurring"`           | token   |
| `plan.interval`             | `plan.interval:"months"`          | token   |
| `plan.interval_count`       | `plan.interval_count:1`           | numeric |
| `plan.trial_interval`       | `plan.trial_interval:"days"`      | token   |
| `plan.trial_interval_count` | `plan.trial_interval_count:14`    | numeric |
| `plan.archived_at`          | `plan.archived_at:null`           | date    |
| `plan.price.currency`       | `plan.price.currency:"USD"`       | token   |
| `plan.price.amount`         | `plan.price.amount>1000`          | numeric |
| `plan.trial_price.currency` | `plan.trial_price.currency:"USD"` | token   |
| `plan.trial_price.amount`   | `plan.trial_price.amount:0`       | numeric |
| `plan.tax.collect_tax`      | `plan.tax.collect_tax:"true"`     | token   |

#### Metadata

| Field                        | Usage                                 | Type  |
| ---------------------------- | ------------------------------------- | ----- |
| `metadata["<key>"]`          | `metadata["plan_tier"]:"gold"`        | token |
| `plan.metadata["<key>"]`     | `plan.metadata["feature"]:"priority"` | token |
| `customer.metadata["<key>"]` | `customer.metadata["tier"]:"premium"` | token |

<Info>
  The `status` field accepts values like `ACTIVE`, `CANCELLED`, `PAST_DUE`, `PAUSED`, `TRIAL`, `SCHEDULED_FOR_CANCELLATION`.
</Info>

### Query fields for Plans

| Field                          | Usage                                | Type    |
| ------------------------------ | ------------------------------------ | ------- |
| `id`                           | `id:"price_a5b8..."`                 | token   |
| `name`                         | `name~"Pro"`                         | string  |
| `type`                         | `type:"recurring"`                   | token   |
| `created_at`                   | `created_at>1620310503`              | date    |
| `updated_at`                   | `updated_at>1620310503`              | date    |
| `archived_at`                  | `archived_at:null`                   | date    |
| `interval`                     | `interval:"months"`                  | token   |
| `interval_count`               | `interval_count:1`                   | numeric |
| `trial_interval`               | `trial_interval:"days"`              | token   |
| `trial_interval_count`         | `trial_interval_count:14`            | numeric |
| `price.default.currency`       | `price.default.currency:"USD"`       | token   |
| `price.default.amount`         | `price.default.amount>1000`          | numeric |
| `trial_price.default.currency` | `trial_price.default.currency:"USD"` | token   |
| `trial_price.default.amount`   | `trial_price.default.amount:0`       | numeric |
| `tax.collect_tax`              | `tax.collect_tax:"true"`             | token   |
| `metadata["<key>"]`            | `metadata["feature"]:"priority"`     | token   |

<Info>
  The `interval` and `trial_interval` fields accept `days`, `months`, `years`. The `type` field accepts `recurring`, `one-off`.
</Info>

***

## Parameters

All search endpoints accept the same parameters:

<ParamField query="query" type="string" required>
  The search query string. See the [search query language](#search-query-language) and the list of supported [query fields for each resource](#supported-query-fields-for-each-resource).
</ParamField>

<ParamField query="limit" type="integer" default="10">
  A limit on the number of objects to return. Limit can range between 1 and 100, and the default is 10.
</ParamField>

<ParamField query="page" type="string">
  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 pages.
</ParamField>

## Response format

A dictionary with a `data` property that contains an array of up to `limit` results. If no objects match the query, the resulting array will be empty.

<ResponseField name="object" type="string" required>
  The resource collection name — one of `payments`, `customers`, `subscriptions`, or `plans`.
</ResponseField>

<ResponseField name="url" type="string" required>
  The URL of the search endpoint that was called.
</ResponseField>

<ResponseField name="has_more" type="boolean" required>
  Whether there are more results available beyond this page.
</ResponseField>

<ResponseField name="next_page" type="string">
  A cursor to use as the `page` parameter for the next request. `null` if there are no more results.
</ResponseField>

<ResponseField name="total_count" type="integer" required>
  The total number of objects matching the query.
</ResponseField>

<ResponseField name="data" type="array" required>
  An array of result objects matching the query. Each entry is a full resource object (the same shape returned by the corresponding `GET /{resource}/{id}` endpoint).
</ResponseField>

<RequestExample>
  ```bash curl theme={"system"}
  curl -G https://api.paynext.com/customers \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "X-API-Version: 2.0.0" \
    --data-urlencode "query=full_name:'Alice Johnson' AND metadata['tier']:'premium'"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={"system"}
  {
    "object": "customers",
    "url": "/customers",
    "has_more": false,
    "next_page": null,
    "total_count": 1,
    "data": [
      {
        "id": "cus_b8d0fe7e-3a7f-4b5f-a68b-d31358b49c3f",
        "created_at": "2025-05-28T14:00:00Z",
        "updated_at": "2025-05-28T14:05:00Z",
        "external_id": "ext_001",
        "full_name": "Alice Johnson",
        "email": "alice.johnson@example.com",
        "metadata": {
          "tier": "premium"
        },
        "address": {
          "city": "San Francisco",
          "country": "US",
          "line1": "123 Market Street",
          "line2": "Suite 400",
          "postal_code": "94105",
          "state": "CA"
        },
        "phone": "+1-555-123-4567"
      }
    ]
  }
  ```
</ResponseExample>

***

## Limitations

### Rate limits

Search endpoints are rate-limited to **20 requests per second** per API key. For workloads requiring analytics or bulk data export, consider using webhooks or scheduled data pulls.

### Data freshness

Don't use search for read-after-write flows (for example, searching immediately after a payment is created) because the data may not be immediately available to search. Under normal operating conditions, data is searchable in under 1 minute.

For read-after-write flows that require immediate data availability, use the standard list APIs with individual filter parameters.

### Query constraints

* Maximum **10 clauses** per query
* You cannot combine `AND` and `OR` in the same query
* On Payments and Customers, all `OR` clauses must target the same field (Subscriptions and Plans allow `OR` across different fields)
* No parentheses for operator precedence
* Substring matching (`~`) requires a minimum of 3 characters
* Space-separated clauses default to `AND` logic

<Warning>
  In some cases, the data you use to find search results might not match the results that you receive. This can happen because the search index is slightly behind the latest state of the object.
</Warning>