Skip to main content

Customers and subscribers listings

· 2 min read
Albert Tiñena
Albert Tiñena
Chief Technology Officer (CTO)
David Sancho
David Sancho
Principal Engineer & Technical Architect

This release introduces new endpoints to list customers and subscribers through a unified contacts resource, decoupling contact data from orders to enable more flexible integrations.

Unified contact model​

The API now exposes a new contacts resource that represents any person who has provided identifying information through:

  • Order creation (including guest checkout)
  • Account registration
  • Newsletter or marketing subscription
  • Import or external integrations

A contact can be:

  • A customer (has registered or made a purchase)
  • A subscriber (has a marketing state indicating marketing preference)
  • Or both

This unified model allows integrations to work with customer data independently from orders, while also supporting marketing use cases.

Contact detail endpoint​

A new endpoint is available to retrieve a single contact:

GET /api/v1/contacts/{id}

This endpoint returns all relevant information associated with the contact, including:

  • Personal data
  • Registration status
  • Marketing subscription state
  • Default addresses

Contact listing endpoint​

A new endpoint is available to retrieve lists of contacts:

GET /api/v1/contacts?view=customers  
GET /api/v1/contacts?view=subscribers

The view parameter is required and defines the subset of contacts to return.

  • customers → contacts who have registered or made a purchase
  • subscribers → contacts with a defined marketing state (subscribed or unsubscribed)

This endpoint includes support for:

  • Advanced filtering
  • Sorting
  • Pagination

Example filters include:

  • Email
  • Registration status
  • B2B status, internal classification, etc.
  • Marketing subscription state
  • Creation and last access dates

How it works​

  • contacts is the source of truth for customer and subscriber data
  • The view parameter defines the projection of the dataset
  • A contact may appear in multiple views if it satisfies the conditions.

Summary​

This release improves integration capabilities by:

  • Exposing a new resource, unifying customers and subscribers into a single one
  • Decoupling customer data from orders
  • Exposing subscribers to unlock new possiblities
  • Enabling flexible filtering through explicit views

These changes provide a more consistent and scalable foundation for external systems such as ERPs, CRMs, and marketing platforms.

What's next​

Upcoming improvements will focus on:

  • Expanding API coverage to support broader ERP and integration use cases
  • Continuing to evolve the API as a robust integration platform

👉 API Overview