Payments
Filter Payments
Learn how to filter payments by payment fields and metadata using the endpoint GET /stores//payments/filter.
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 theAuthorization 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 ofpage. The cursor is supported only when sortBy=createdAt (default):
- Make the first call without
cursor. - If
hasMoreistrue, the response contains thenextCursorfield. - Send that
nextCursorin thecursorparameter of the next request to fetch the next page.
nextCursor, hasMore and limit (without total/totalPages):
cursorandpagecannot be used together (400 INVALID_PAGINATION).- Using
cursorwith asortByother thancreatedAtreturns400 INVALID_CURSOR_SORT. nextCursor: nullwithhasMore: falseindicate the end of the list (the API responds200with an empty array).- Very broad metadata filters may still return
422 FILTER_TOO_BROAD.
✅ Example request
🧠 Nested metadata example
Filter bymetadata.items[0].product.sold = 19:
📦 Success response (200)
The first call (withoutcursor) already returnsnextCursorandhasMorein 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→limitoutside the allowed range (1to100)400 INVALID_PAGINATION_PAGE→ invalidpage400 INVALID_PAGINATION_CURSOR→ invalid or malformedcursor400 INVALID_PAGINATION→pageandcursorused together400 INVALID_CURSOR_SORT→cursorused with asortByother thancreatedAt401 API_KEY_NOT_PROVIDED→ missingAuthorizationheader401 INVALID_API_KEY→ invalid API key401 UNAUTHENTICATED→ unauthenticated user403 USER_DISABLED→ user disabled or deleted403 NO_ACTIVE_SUBSCRIPTION→ inactive or expired plan404 STORE_NOT_FOUND→ store not found or does not belong to the account422 FILTER_TOO_BROAD→ metadata filter too broad; refinemetadataKey/metadataValue429 RATE_LIMIT_EXCEEDED→ plan per-minute rate limit exceeded500 INTERNAL_SERVER_ERROR→ internal error503 SERVICE_UNAVAILABLE→ service temporarily unavailable