Subscriptions

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 (ISO 8601)	`:`, `>`, `>=`, `<`, `<=`
`updated_at`	date (ISO 8601)	`:`, `>`, `>=`, `<`, `<=`
`current_period_start`	date (ISO 8601)	`:`, `>`, `>=`, `<`, `<=`
`current_period_end`	date (ISO 8601)	`:`, `>`, `>=`, `<`, `<=`
`next_billing_date`	date (ISO 8601)	`:`, `>`, `>=`, `<`, `<=`
`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 (ISO 8601)	`:`, `>`, `>=`, `<`, `<=`
`customer.updated_at`	date (ISO 8601)	`:`, `>`, `>=`, `<`, `<=`
`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 (ISO 8601, 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)	`:`

GET

subscriptions

Find subscriptions

curl --request GET \
  --url https://sandbox-api.paynext.com/subscriptions \
  --header 'X-API-Version: <x-api-version>'

{
  "object": "subscriptions",
  "total_count": 142,
  "url": "/v1/subscriptions",
  "data": [
    {
      "id": "sub_123e4567-e89b-12d3-a456-426614174000",
      "current_period_end": "<string>",
      "current_period_start": "<string>",
      "customer": {
        "id": "cus_b8d0fe7e-3a7f-4b5f-a68b-d31358b49c3f",
        "address": {
          "city": "San Francisco",
          "line1": "123 Market Street",
          "line2": "Suite 400",
          "postal_code": "94105",
          "state": "CA"
        },
        "email": "alice.johnson@example.com",
        "external_id": "ext_001",
        "full_name": "Alice Johnson",
        "phone": "+1-555-123-4567",
        "metadata": {
          "key": "value"
        },
        "created_at": "2025-05-28T14:00:00Z",
        "updated_at": "2025-05-28T14:05:00Z"
      },
      "next_billing_date": "2025-06-26T12:00:00Z",
      "past_due": {
        "attempt_count": 2,
        "max_attempts_count": 7
      },
      "plan": {
        "id": "price_1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
        "archived_at": "2025-06-01T10:00:00Z",
        "interval": "days",
        "interval_count": 1,
        "name": "Pro Plan",
        "price": {
          "amount": 1999,
          "currency": "AED"
        },
        "tax": {
          "collect_tax": "<unknown>"
        },
        "trial_interval": "days",
        "trial_interval_count": 14,
        "trial_price": {
          "amount": 1999,
          "currency": "AED"
        },
        "type": "recurring"
      },
      "metadata": {
        "key": "value"
      },
      "created_at": "2025-05-26T10:00:00Z",
      "updated_at": "2025-05-27T10:00:00Z"
    }
  ],
  "has_more": false,
  "next_page": null
}

Headers

X-API-Version

enum<string>

required

Specifies the version of the API to use

Available options:

2.0.0

Query Parameters

query

string

required

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.

limit

integer

default:10

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

Required range: 1 <= x <= 100

page

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

Response

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.

object

enum<string>

String representing the object's type. Value is always subscriptions.

Available options:

subscriptions

Example:

"subscriptions"

total_count

integer

The accurate total number of records matching the query (not capped at 10,000). Returned alongside the cursor pagination fields.

Example:

142

url

string

The URL for accessing this list.

Example:

"/v1/subscriptions"

data

object[]

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.

Show child attributes

has_more

boolean

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

string | null

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

Create a subscriptionCreates a new subscription for a customer. The subscription will be billed according to the specified plan.

⌘I

Find subscriptions

curl --request GET \
  --url https://sandbox-api.paynext.com/subscriptions \
  --header 'X-API-Version: <x-api-version>'

{
  "object": "subscriptions",
  "total_count": 142,
  "url": "/v1/subscriptions",
  "data": [
    {
      "id": "sub_123e4567-e89b-12d3-a456-426614174000",
      "current_period_end": "<string>",
      "current_period_start": "<string>",
      "customer": {
        "id": "cus_b8d0fe7e-3a7f-4b5f-a68b-d31358b49c3f",
        "address": {
          "city": "San Francisco",
          "line1": "123 Market Street",
          "line2": "Suite 400",
          "postal_code": "94105",
          "state": "CA"
        },
        "email": "alice.johnson@example.com",
        "external_id": "ext_001",
        "full_name": "Alice Johnson",
        "phone": "+1-555-123-4567",
        "metadata": {
          "key": "value"
        },
        "created_at": "2025-05-28T14:00:00Z",
        "updated_at": "2025-05-28T14:05:00Z"
      },
      "next_billing_date": "2025-06-26T12:00:00Z",
      "past_due": {
        "attempt_count": 2,
        "max_attempts_count": 7
      },
      "plan": {
        "id": "price_1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
        "archived_at": "2025-06-01T10:00:00Z",
        "interval": "days",
        "interval_count": 1,
        "name": "Pro Plan",
        "price": {
          "amount": 1999,
          "currency": "AED"
        },
        "tax": {
          "collect_tax": "<unknown>"
        },
        "trial_interval": "days",
        "trial_interval_count": 14,
        "trial_price": {
          "amount": 1999,
          "currency": "AED"
        },
        "type": "recurring"
      },
      "metadata": {
        "key": "value"
      },
      "created_at": "2025-05-26T10:00:00Z",
      "updated_at": "2025-05-27T10:00:00Z"
    }
  ],
  "has_more": false,
  "next_page": null
}