API documentation

Customers

GET/customers

List customers

Use this endpoint to discover Stripe customer IDs before retrieving a profile or its invoices. The list includes only customers that already have at least one invoice in this account and mode.

Request
Build the URL with the parameters below and send the code in the Authorization header.
GEThttps://stripe-ix.betacode.tech/api/v1/customers

Inputs and parameters

pagequeryinteger

Page to return. Values below 1 use the default.

Optional · Default: 1

page_sizequeryinteger

Number of records per page. The maximum is 50.

Optional · Default: 10

qquerystring

Search by name, email, company, tax ID or phone.

Optional

customer_kindqueryenum

Customer type: company or individual.

Optional

Request example

curl "https://stripe-ix.betacode.tech/api/v1/customers?page=1&page_size=20&q=acme&customer_kind=company" \
  -H "Authorization: Bearer ixp_test_YOUR_ACCESS_CODE" \
  -H "Accept: application/json"
Response
On success, this endpoint returns JSON with Content-Type application/json.

Output example

{
  "customers": [
    {
      "id": "cus_Q1w2E3r4",
      "display_name": "Acme, Lda.",
      "name": "Ana Silva",
      "email": "financeiro@acme.pt",
      "company_name": "Acme, Lda.",
      "tax_id": "PT509123456",
      "invoice_count": 12,
      "pending_invoice_count": 1,
      "country": "PT",
      "has_billing_address": true,
      "is_company": true,
      "vat_regime": {
        "regime": "normal",
        "exemption_reason": null
      },
      "preferred_tax": {
        "ix_tax_rate_id": 1,
        "ix_tax_rate_name": "IVA23",
        "ix_tax_percent": 23
      }
    }
  ],
  "page": 1,
  "page_size": 20,
  "total": 1,
  "total_pages": 1,
  "source": "mongo"
}

Behavior

  • Scope is the Stripe account and mode of the access code. There is no account parameter.
  • An empty list is a valid page, not a 404.
  • A customer_kind other than company or individual returns 400.

Integration notes

  • vat_regime.regime is normal, exempt or reverse.
  • preferred_tax is null when the customer has no InvoiceXpress rate yet.
  • The profile, including address and phone, remains at GET /client/:customerId.