Skip to main content
GET
Filter payments

📌 Endpoint

GET /stores/{storeId}/payments/filter Filters payments of a store with support for pagination, sorting and metadata filters.

🔐 Authentication

Private route. Send the Authorization header with your API key and active plan.

🧾 Route parameter


🔎 Query params


🔄 Cursor pagination

For large lists (more than ~100 items), prefer cursor pagination instead of page. The cursor is supported only when sortBy=createdAt (default):
  1. Make the first call without cursor.
  2. If hasMore is true, the response contains the nextCursor field.
  3. Send that nextCursor in the cursor parameter of the next request to fetch the next page.
In cursor mode, pagination is returned only with nextCursor, hasMore and limit (without total/totalPages):
  • cursor and page cannot be used together (400 INVALID_PAGINATION).
  • Using cursor with a sortBy other than createdAt returns 400 INVALID_CURSOR_SORT.
  • nextCursor: null with hasMore: false indicate the end of the list (the API responds 200 with an empty array).
  • Very broad metadata filters may still return 422 FILTER_TOO_BROAD.

✅ Example request


🧠 Nested metadata example

Filter by metadata.items[0].product.sold = 19:

📦 Success response (200)

The first call (without cursor) already returns nextCursor and hasMore in the pagination, allowing cursor pagination to start without extra calls.

⚠️ Possible errors

  • 400 INVALID_DATA → invalid parameters (including timestamps not in RFC3339/ISO-8601 format)
  • 400 INVALID_PAGINATION_LIMIT → limit outside the allowed range (1 to 100)
  • 400 INVALID_PAGINATION_PAGE → invalid page
  • 400 INVALID_PAGINATION_CURSOR → invalid or malformed cursor
  • 400 INVALID_PAGINATION → page and cursor used together
  • 400 INVALID_CURSOR_SORT → cursor used with a sortBy other than createdAt
  • 401 API_KEY_NOT_PROVIDED → missing Authorization header
  • 401 INVALID_API_KEY → invalid API key
  • 401 UNAUTHENTICATED → unauthenticated user
  • 403 USER_DISABLED → user disabled or deleted
  • 403 NO_ACTIVE_SUBSCRIPTION → inactive or expired plan
  • 404 STORE_NOT_FOUND → store not found or does not belong to the account
  • 422 FILTER_TOO_BROAD → metadata filter too broad; refine metadataKey/metadataValue
  • 429 RATE_LIMIT_EXCEEDED → plan per-minute rate limit exceeded
  • 500 INTERNAL_SERVER_ERROR → internal error
  • 503 SERVICE_UNAVAILABLE → service temporarily unavailable

Authorizations

Authorization
string
header
default:YOUR_API_KEY_HERE
required

Path Parameters

storeId
string
required
Required string length: 1 - 50

Query Parameters

page
integer
default:1
Required range: x >= 1
limit
integer
default:20
Required range: 1 <= x <= 100
cursor
string

Opaque cursor from previous page (do not combine with page; only valid when sortBy=createdAt).

id
string<uuid>
uuid
string<uuid>
name
string
email
string<email>
cpf
string
status
enum<string>
Available options:
PENDING,
APPROVED,
REJECTED,
CANCELLED,
REFUNDED,
CHARGED_BACK,
EXPIRED
price
number
minPrice
number
maxPrice
number
coupon
boolean
gateway
enum<string>
Available options:
MERCADOPAGO,
EFI_BANK,
ASAAS,
STRIPE
shipment
enum<string>
Available options:
PENDING,
PREPARING,
SHIPPED,
DELIVERED,
RETURNED,
CANCELLED
createdAtFrom
string<date-time>
createdAtTo
string<date-time>
updatedAtFrom
string<date-time>
updatedAtTo
string<date-time>
productId
string<uuid>
metadataKey
string
metadataValue
string
sortBy
enum<string>
default:createdAt
Available options:
createdAt,
updatedAt,
price,
name,
email
sortOrder
enum<string>
default:desc
Available options:
asc,
desc

Response

Filter payments.

code
string
required
Example:

"PAYMENTS_FILTERED"

payments
object[]
required
pagination
object
required