Version
GET

List payments

/v1/payments in the Payments API.

curl "https://api.subscriby.net/v1/payments?status=failed&from=2026-11-01" \  -H "Authorization: Bearer $SUBSCRIBY_TOKEN"

The payments across every project the token reaches, newest first, paged with page and per_page (default 25; limit is accepted as an alias). project_id keeps to one project, status to one of successful, failed, pending or refunded, plan_id and method_id to one plan or gateway, connector to the projects whose live installation is that connector, from and to to a span of moments (a date alone for to runs to the end of that day), and search matches the gateway references, the subscription's payment id, or a member, plan or project name, as the page's search box does.

A token minted with scope:project:<uuid> entries lists only the payments of those projects, and a payment of any other project is 404 RESOURCE_NOT_FOUND on the detail endpoint. Amounts are as paid, in the currency of each row, never converted; the raw payload the gateway sent is kept for audit and never travels.

GET
/v1/payments

Requires ability

The token must hold this ability, or the call is refused with 403.

Runs the same action from an agent, behind the same ability.

Authorization

bearerToken
AuthorizationBearer <token>

A personal access token minted on the dashboard under Settings, then Tokens, sent as Authorization: Bearer sbt_live_…. The token carries the abilities each endpoint lists under Requires ability and is frozen to one team.

In: header

Query Parameters

project_id?|

Keep to one project's payments.

Formatuuid
status?|

Match one status: successful, failed, pending or refunded. An unknown value is refused.

plan_id?|

Keep to payments for one plan.

Formatuuid
method_id?|

Keep to payments through one payment method.

Formatuuid
connector?|

Keep to projects whose live installation is this connector, by key.

Lengthlength <= 64
from?|

Keep to payments that occurred at or after this moment, ISO 8601 or a date.

Formatdate-time
to?|

Keep to payments that occurred at or before this moment, ISO 8601 or a date; the end of that day when a date alone is given.

Formatdate-time
search?|

Match the gateway references, the subscription's payment id, or the member's, plan's or project's name, as the page's search box does.

Lengthlength <= 120
page?integer

The 1-based page to return. A page past the last answers an empty data array with meta.total still filled, so a loop can stop without guessing.

Range1 <= value
Default1
per_page?integer

Rows per page, 1 to 100. A higher value clamps to the cap silently. Defaults to 25.

Range1 <= value <= 100
Default25
sort_by?string

The column to order by. Defaults to created_at; a column the endpoint does not offer falls back to the default rather than failing.

Default"created_at"
sort_direction?string

asc or desc. Defaults to desc.

Default"desc"

Value in

  • "asc"
  • "desc"
limit?integer

Legacy alias of per_page, kept for clients that predate it. per_page wins when both are sent.

Range1 <= value <= 100

Responses

200OK

The page of payments, newest first.

401Unauthorized

The request carries no bearer token, or one that is revoked, malformed, or minted for another environment (an sbt_test_ token on production).

403Forbidden

The token is valid but does not carry the ability this endpoint requires; error.context.required_ability names the one to grant. An endpoint that also checks who owns a row or which tier the account is on answers FORBIDDEN, TEAM_TIER_REQUIRED or CONNECTOR_TIER_REQUIRED with the same status, and says so in its own description.

422Validation failed

The payload broke a rule, and error.fields maps each offending key to its messages. A refusal from the domain, such as a plan that cannot go on sale or a member who cannot be removed, uses the same code with error.message saying why and no fields. On this endpoint: VALIDATION_FAILED: when status is not one of the four statuses, an id is not a UUID, a bound is not a date or to is before from.

429Too many requests

The token has spent its 300 requests a minute or 10,000 an hour; Retry-After says when the next one is accepted.

How is this guide?

Last updated on