Saltar al contenido principal
GET
Filter payments

📌 Endpoint

GET /stores/{storeId}/payments/filter Filtra los pagos de una tienda con soporte de paginación, ordenación y filtros por metadata.

🔐 Autenticación

Ruta privada. Envía el header Authorization con tu API key y plan activo.

🧾 Parámetro de ruta


🔎 Query params


🔄 Paginación por cursor

Para listas grandes (más de ~100 elementos), prefiere la paginación por cursor en lugar de page. El cursor solo se soporta cuando sortBy=createdAt (por defecto):
  1. Realiza la primera llamada sin cursor.
  2. Si hasMore es true, la respuesta trae el campo nextCursor.
  3. Envía ese nextCursor en el parámetro cursor de la siguiente solicitud para buscar la página siguiente.
En modo cursor, la paginación se devuelve solo con nextCursor, hasMore y limit (sin total/totalPages):
  • cursor y page no pueden usarse juntos (400 INVALID_PAGINATION).
  • Usar cursor con sortBy distinto de createdAt devuelve 400 INVALID_CURSOR_SORT.
  • nextCursor: null con hasMore: false indican el fin de la lista (la API responde 200 con array vacío).
  • Los filtros de metadata muy amplios pueden seguir devolviendo 422 FILTER_TOO_BROAD.

✅ Ejemplo de solicitud


🧠 Ejemplo para metadata anidada

Filtrar por metadata.items[0].product.sold = 19:

📦 Respuesta de éxito (200)

La primera llamada (sin cursor) ya devuelve nextCursor y hasMore en la paginación, permitiendo iniciar la paginación por cursor sin llamadas extras.

⚠️ Posibles errores

  • 400 INVALID_DATA → parámetros inválidos (incluidas fechas que no estén en formato RFC3339/ISO-8601)
  • 400 INVALID_PAGINATION_LIMIT → limit fuera del intervalo permitido (1 a 100)
  • 400 INVALID_PAGINATION_PAGE → page inválida
  • 400 INVALID_PAGINATION_CURSOR → cursor inválido o malformado
  • 400 INVALID_PAGINATION → page y cursor usados juntos
  • 400 INVALID_CURSOR_SORT → cursor usado con sortBy distinto de createdAt
  • 401 API_KEY_NOT_PROVIDED → header Authorization no enviado
  • 401 INVALID_API_KEY → API key inválida
  • 401 UNAUTHENTICATED → usuario no autenticado
  • 403 USER_DISABLED → usuario desactivado o eliminado
  • 403 NO_ACTIVE_SUBSCRIPTION → plan inactivo o expirado
  • 404 STORE_NOT_FOUND → tienda no encontrada o no pertenece a la cuenta
  • 422 FILTER_TOO_BROAD → filtro por metadata muy amplio; refine metadataKey/metadataValue
  • 429 RATE_LIMIT_EXCEEDED → límite de solicitudes por minuto del plan excedido
  • 500 INTERNAL_SERVER_ERROR → error interno
  • 503 SERVICE_UNAVAILABLE → servicio temporalmente no disponible

Autorizaciones

Authorization
string
header
predeterminado:YOUR_API_KEY_HERE
requerido

Parámetros de ruta

storeId
string
requerido
Required string length: 1 - 50

Parámetros de consulta

page
integer
predeterminado:1
Rango requerido: x >= 1
limit
integer
predeterminado:20
Rango requerido: 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>
Opciones disponibles:
PENDING,
APPROVED,
REJECTED,
CANCELLED,
REFUNDED,
CHARGED_BACK,
EXPIRED
price
number
minPrice
number
maxPrice
number
coupon
boolean
gateway
enum<string>
Opciones disponibles:
MERCADOPAGO,
EFI_BANK,
ASAAS,
STRIPE
shipment
enum<string>
Opciones disponibles:
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>
predeterminado:createdAt
Opciones disponibles:
createdAt,
updatedAt,
price,
name,
email
sortOrder
enum<string>
predeterminado:desc
Opciones disponibles:
asc,
desc

Respuesta

Filter payments.

code
string
requerido
Ejemplo:

"PAYMENTS_FILTERED"

payments
object[]
requerido
pagination
object
requerido