Search - Documentation

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'"

{
  "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"
    }
  ]
}

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 and Response format below. To create a search query, review the search query language and reference the query fields of the resource:

Query fields for Payments
Query fields for Customers
Query fields for Subscriptions
Query fields for Plans

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.

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.

curl

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.

curl

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.

curl

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.

curl

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.

curl

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.

curl

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 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. 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
`>`, `<`, `>=`, `<=`	`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

The payment_status field accepts the following values: PENDING, FAILED, AUTHORIZED, SETTLING, SETTLED, DECLINED, BLOCKED, CANCELLED.

The payment_method.type field accepts values like CARD, PIX, PAYPAL, CASHAPP, APPLEPAY, GOOGLEPAY, VENMO, AMAZONPAY.

The payment_token_type field accepts: CARD_PAN, NETWORK_TOKEN, PROCESSOR_TOKEN.

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.

customer.email and customer.external_id on payments match against the customer associated with the payment.

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

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

The subscriptions.status field accepts values like ACTIVE, CANCELLED, PAST_DUE, PAUSED, TRIAL, SCHEDULED_FOR_CANCELLATION.

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

The status field accepts values like ACTIVE, CANCELLED, PAST_DUE, PAUSED, TRIAL, SCHEDULED_FOR_CANCELLATION.

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

The interval and trial_interval fields accept days, months, years. The type field accepts recurring, one-off.

Parameters

All search endpoints accept the same parameters:

string

required

The search query string. See the search query language and the list of supported query fields for each resource.

integer

default:"10"

A limit on the number of objects to return. Limit can range between 1 and 100, and the default is 10.

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.

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.

string

required

The resource collection name — one of payments, customers, subscriptions, or plans.

string

required

The URL of the search endpoint that was called.

boolean

required

Whether there are more results available beyond this page.

string

A cursor to use as the page parameter for the next request. null if there are no more results.

integer

required

The total number of objects matching the query.

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

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'"

{
  "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"
    }
  ]
}

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

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.

⌘I

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'"

{
  "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"
    }
  ]
}

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

​Examples

​Payments metadata search

​Payments by status and amount

​Customers email search

​Negation filter

​Numeric filter

​Combining multiple filters

​Search query language

​Query structure and terminology

​Negation

​Field types, substring matching, and numeric comparators

​Quotes

​Metadata

​Null operator

​Search syntax

​Supported query fields for each resource

​Query fields for Payments

​Core

​Customer

​Subscription

​Processor

​Payment method and card

​Network token

​PayPal payer info

​Processor customer

​Refund

​Tax

​3-D Secure

​Decline information

​AVS / CVC checks

​Processor identifiers

​Fraud prevention

​Metadata

​Query fields for Customers

​Core

​Address

​Payment methods

​Subscriptions

​Subscription plan

​Metadata

​Query fields for Subscriptions

​Core

​Customer

​Plan

​Metadata

​Query fields for Plans

​Parameters

​Response format

​Limitations

​Rate limits

​Data freshness

​Query constraints

Examples

Payments metadata search

Payments by status and amount

Customers email search

Negation filter

Numeric filter

Combining multiple filters

Search query language

Query structure and terminology

Negation

Field types, substring matching, and numeric comparators

Quotes

Metadata

Null operator

Search syntax

Supported query fields for each resource

Query fields for Payments

Core

Customer

Subscription

Processor

Payment method and card

Network token

PayPal payer info

Processor customer

Refund

Tax

3-D Secure

Decline information

AVS / CVC checks

Processor identifiers

Fraud prevention

Metadata

Query fields for Customers

Core

Address

Payment methods

Subscriptions

Subscription plan

Metadata

Query fields for Subscriptions

Core

Customer

Plan

Metadata

Query fields for Plans

Parameters

Response format

Limitations

Rate limits

Data freshness

Query constraints