Customers

Customer management for invoice recipients.
Store customer details including address and tax information for use in invoice creation.

Create a new customer

POST/customers

Create a new customer for use in invoices.
Store customer details including name, address, and tax information.
All fields except name are optional.

Request

Header parameters

entity_idstringoptional

Entity ID on which the request is made. Optional - defaults to the first created entity if not provided.

Body parameters

namestringrequired

emailstringoptional

tax_numberstringoptional

addressstringoptional

citystringoptional

country_codestringoptional

metadataobjectoptional

Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.

Other parameters

address_2stringoptional

post_codestringoptional

statestringoptional

countrystringoptional

curl -X POST "https://eu.spaceinvoices.com/customers" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-entity-id: YOUR_ENTITY_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Minimal Customer"
  }'

Example:

Response

json

{
  "id": "cust_6595a27b5d35015c3ef0c3fd",
  "name": "Minimal Customer",
  "email": null,
  "address": null,
  "address_2": null,
  "post_code": null,
  "city": null,
  "state": null,
  "country": null,
  "country_code": null,
  "tax_number": null,
  "entity_id": "ent_6595a27b5d35015c3ef0c3fd",
  "metadata": {},
  "vies": null,
  "created_at": "2024-01-01T00:00:00.000Z",
  "updated_at": "2024-09-01T00:00:00.000Z"
}

Example:

List all customers

GET/customers

Retrieve a paginated list of customers with optional filtering and sorting.
Supports cursor-based pagination, flexible JSON querying with MongoDB-style operators, full-text search, and sorting.

Request

Header parameters

entity_idstringoptional

Entity ID on which the request is made. Optional - defaults to the first created entity if not provided.

Query parameters

limitintegeroptional

Number of results per request.

Default: 10

next_cursorstringoptional

Cursor to fetch the next page of results. Use the value from pagination.next_cursor in the previous response.

prev_cursorstringoptional

Cursor to fetch the previous page of results. Use the value from pagination.prev_cursor in the previous response.

include_total_countbooleanoptional

Whether to include the total count of items in pagination.total.
Default is true.
When false, pagination.total returns -1 for better performance.

order_byoptional

querystring<json>optional

JSON query object for filtering results. Supports MongoDB-style operators.

Supported operators:
- equals or direct value - Exact match (default)
- gte - Greater than or equal
- lte - Less than or equal
- gt - Greater than
- lt - Less than
- in - Value in array
- notIn - Value not in array
- contains - String contains (case-insensitive)
- startsWith - String starts with
- endsWith - String ends with
- between - Value between two numbers/dates [min, max]

Allowed fields: id, name, address, city, country, tax_number, email, created_at, updated_at

Examples:
- {"total": {"gte": 1000}} - Invoices over 1000
- {"customer.name": {"contains": "Acme"}} - Customer name contains "Acme"
- {"date": {"between": ["2025-01-01", "2025-12-31"]}} - Date range

searchstringoptional

Full-text search query to filter results across multiple fields.
Searches are case-insensitive and match partial strings.
Searches across all text fields including names, descriptions, addresses, and metadata values.

curl "https://eu.spaceinvoices.com/customers" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-entity-id: YOUR_ENTITY_ID"

Response

Returns

dataarray

paginationobject

Pagination metadata including cursors and result counts

json

{
  "data": [
    {
      "id": "cust_6595a27b5d35015c3ef0c3fd",
      "name": "Minimal Customer",
      "email": null,
      "address": null,
      "address_2": null,
      "post_code": null,
      "city": null,
      "state": null,
      "country": null,
      "country_code": null,
      "tax_number": null,
      "entity_id": "ent_6595a27b5d35015c3ef0c3fd",
      "metadata": {},
      "vies": null,
      "created_at": "2024-01-01T00:00:00.000Z",
      "updated_at": "2024-09-01T00:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 1,
    "next_cursor": null,
    "prev_cursor": null,
    "has_more": false
  }
}