Skip to content
Bottle

List customers

GET
/customers
curl --request GET \
  --url 'https://example.com/customers?includeArchived=true&limit=50&offset=0&sort=name&dir=asc&owing=true' \
  --cookie bottle.session_token=<bottle.session_token>

Returns the tenant’s customers, ordered by trading name. Archived customers are excluded unless includeArchived=true.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
q

Search trading name

string
<= 100 characters

Search trading name

includeArchived
string
default: false
Allowed values: true false
limit
integer
default: 50 >= 1 <= 200
offset
integer | null
0
sort
string
default: name
Allowed values: name owed overdue
dir
string
Allowed values: asc desc
owing
string
default: false
Allowed values: true false

Responses

Section titled “Responses”

200

Section titled “200”

Customers

Media typeapplication/json
object
items
required
Array<object>
object
id
required

UUID v7

string format: uuid
tradingName
required
string
>= 1 characters <= 160 characters
kind
required
string
Allowed values: commercial domestic
legalName
required
string | null
<= 200 characters
email
required
string | null format: email
phone
required
string | null
/^\+?[\d\s()-]{7,20}$/
paymentTerms
required
string
Allowed values: prepaid on_account cash_on_delivery
paymentTermsDays
required
integer | null
<= 120
billingAddressId
required

UUID v7

string | null format: uuid
hireBillingPeriod
required
string | null
Allowed values: weekly monthly quarterly
hireBilledTo
required
string | null format: date
notes
required
string | null
<= 2000 characters
archivedAt
required
string | null format: date-time
mergedIntoId
required

UUID v7

string | null format: uuid
legalHold
required
boolean
erasedAt
required
string | null format: date-time
createdAt
required
string format: date-time
updatedAt
required
string format: date-time
owedPence
required
integer
overduePence
required
integer
total
required
integer
Example
{
  "items": [
    {
      "id": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f",
      "tradingName": "Camden Lock Grill",
      "kind": "commercial",
      "legalName": "Camden Lock Grill Ltd",
      "email": "orders@camdenlockgrill.co.uk",
      "phone": "07700 900123",
      "paymentTerms": "prepaid",
      "billingAddressId": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f",
      "hireBillingPeriod": "weekly",
      "mergedIntoId": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f"
    }
  ]
}

401

Section titled “401”

Not signed in

Media typeapplication/json
object
error
required
string
message
required
string
Example
{
  "error": "not_found",
  "message": "Customer not found"
}

403

Section titled “403”

Not a member of that tenant

Media typeapplication/json
object
error
required
string
message
required
string
Example
{
  "error": "not_found",
  "message": "Customer not found"
}

422

Section titled “422”

Validation failed

Media typeapplication/json
object
error
required
string
Allowed values: validation
message
required
string
issues
required
Array<object>
object
path
required
string
message
required
string
Example
{
  "error": "validation",
  "issues": [
    {
      "path": "email",
      "message": "Invalid email"
    }
  ]
}