Skip to main content
Este documento describe el esquema del parámetro filter para GET /v1/customers. filter no se envía como JSON literal: se envía como query string codificado con qs.

​
Formato general

Ejemplo mínimo: 
GET /v1/customers?filter[name][contains]=juan
Ejemplo con composición lógica: 
GET /v1/customers?filter[AND][0][email][contains]=@empresa.com&filter[OR][0][noPayments]=true

​
Esquema base

Conceptualmente, el esquema es: 
{
  "id": "StringFilter",
  "createdAt": "DateTimeFilter",
  "updatedAt": "DateTimeFilter",
  "name": "StringFilter",
  "archivedAt": "NullableDateTimeFilter",
  "email": "StringFilter",
  "phoneNumber": "StringFilter",
  "secondaryPhoneNumber": "StringFilter",
  "username": "StringFilter",
  "tags": "TagListFilter",
  "invoices": "InvoiceListFilter",
  "receivedAnnouncements": "AnnouncementRecipientListFilter",
  "metadataItem": "MetadataItemFilter",
  "metadata": "MetadataListFilter",
  "assignee": "MemberFilter",
  "noPayments": "BooleanLikeFilter",
  "hasTaxProfiles": "BooleanLikeFilter",
  "AND": ["CustomerFilter"],
  "OR": ["CustomerFilter"]
}

​
Campos soportados

Puedes usar estos campos de primer nivel en filter:
  • id
  • createdAt
  • updatedAt
  • name
  • archivedAt
  • email
  • phoneNumber
  • secondaryPhoneNumber
  • username
  • tags
  • invoices
  • receivedAnnouncements
  • metadataItem
  • metadata
  • assignee
  • noPayments
  • hasTaxProfiles
  • AND
  • OR

​
Operadores comunes

Los operadores disponibles dependen del tipo de campo:
  • String (name, email, username, etc.): equals, contains, startsWith, endsWith, in, notIn
  • Fecha (createdAt, updatedAt, archivedAt): equals, gt, gte, lt, lte
  • Booleano (noPayments, hasTaxProfiles): equals
Para filtros relacionales (tags, invoices, metadata, assignee) usa operadores de lista/relación como some, every, none, según el objeto anidado.

​
Ejemplos

​
Filtrar por nombre

GET /v1/customers?filter[name][contains]=Alicia

​
Filtrar por correo exacto

GET /v1/customers?filter[email][equals]=alicia@ejemplo.com

​
Filtrar por clientes sin pagos

GET /v1/customers?filter[noPayments]=true

​
Combinar filtros con AND

GET /v1/customers?filter[AND][0][name][contains]=Alicia&filter[AND][1][hasTaxProfiles]=true

​
Combinar AND y OR

GET /v1/customers?filter[AND][0][name][contains]=Alicia&filter[AND][1][OR][0][email][contains]=@empresa.com&filter[AND][1][OR][1][noPayments]=true

​
Orden y paginacion junto con filtros

GET /v1/customers?filter[name][contains]=Alicia&orderBy=createdAt=desc&take=20&skip=0

​
Construccion recomendada con qs

import qs from 'qs';

const filter = {
  AND: [{ name: { contains: 'Alicia' } }, { hasTaxProfiles: { equals: true } }],
};

const query = qs.stringify({ filter, take: 20, skip: 0 }, { encodeValuesOnly: true });
// filter[AND][0][name][contains]=Alicia&filter[AND][1][hasTaxProfiles][equals]=true&take=20&skip=0

​
Recomendaciones

  • Usa un serializador qs para evitar errores de encoding y de arrays anidados.
  • Empieza con un filtro simple y agrega AND/OR solo cuando sea necesario.
  • Combina filtros con take, skip y orderBy para paginacion consistente.