API reference

Customers

A Customer represents the person or company you're billing. Attach customers to payments, invoices, and subscriptions to mirror your CRM and unlock per-customer dashboards. B2B fields (legal name, tax ID, tax office) live alongside personal fields so the same row works for both audiences.

Create a customer

POST/v1/customersscope: customers:write

At least one of email, phoneE164, or name is required. Email is the de-facto unique identifier — duplicates by email are allowed but the dashboard surfaces them with a warning chip.

Body parameters

`name` string	Display name. Required when neither email nor phone is set.
`email` string	Lowercased before storage; counts as a unique identifier in deduplication queries.
`phoneE164` string	Must match `^\+[1-9]\d{6,14}$`. Validated against libphonenumber.isPossible() rules.
`country` string	ISO-3166 alpha-2 country code.
`city` string	Free-form. Max 120 chars.
`legalName` string	B2B field. Company's registered legal name. Shown on invoices alongside `name`.
`taxId` string	B2B field. VAT / EIN / vergi numarası. Free-form, max 60 chars.
`taxOffice` string	B2B field. Local tax authority (e.g. TR vergi dairesi). Max 120 chars.
`metadata` object	Arbitrary JSON, max 16KB serialized. Echoed back on every retrieve.

curl https://baynoy.com/api/v1/customers \
  -H "Authorization: Bearer sk_live_…" \
  -H "Idempotency-Key: cus-7f9b3d2c" \
  -d '{
    "email": "[email protected]",
    "name": "Acme Industries",
    "legalName": "Acme Industries Ltd.",
    "taxId": "GB123456789",
    "country": "GB"
  }'

Response

{
  "ok": true,
  "data": {
    "id": "8f7e6d5c-4b3a-2918-7654-3210fedcba98",
    "merchantId": "1a2b3c4d-...",
    "name": "Acme Industries",
    "email": "[email protected]",
    "phoneE164": null,
    "country": "GB",
    "city": null,
    "legalName": "Acme Industries Ltd.",
    "taxId": "GB123456789",
    "taxOffice": null,
    "metadata": null,
    "createdAt": "2026-05-27T12:34:56.789Z",
    "updatedAt": "2026-05-27T12:34:56.789Z",
    "deletedAt": null
  }
}

List customers

GET/v1/customersscope: customers:read

Cursor-paginated. Pass cursorfrom the previous response's nextCursor to fetch the next page. Search by free-form q across name, legalName, email, phoneE164 and taxId.

Query parameters

`q` string	Free-text search (case-insensitive).
`cursor` string	Pagination cursor from a previous response.
`pageSize` number	1–100. Default 25.

curl "https://baynoy.com/api/v1/customers?q=acme&pageSize=10" \
  -H "Authorization: Bearer sk_live_…"

Response

{
  "ok": true,
  "data": {
    "items": [
      {
        "id": "8f7e6d5c-...",
        "name": "Acme Industries",
        "email": "[email protected]",
        "legalName": "Acme Industries Ltd.",
        "createdAt": "2026-05-27T12:34:56.789Z"
      }
    ],
    "nextCursor": "eyJpZCI6IjhmN2U2ZDVjLi4ufQ==",
    "hasMore": false
  }
}