Customers API — List, Create, Retrieve, Update, Delete

Manage the customers you bill. Create, update, and archive customer records. All amounts on related invoices use integer minor units.

Customers

A customer represents a person or business you issue invoices to. Every invoice must be linked to a customer. Deleting a customer is a soft-delete — the record is archived (deleted: true) and no longer appears in list results by default, but historical invoices retain full customer details.

Base URL: https://invoice.horizonpay.co/api/v1

---

The customer object

{
  "id": "cus_01hxyz1234567890abcdefghij",
  "object": "customer",
  "name": "Acme Corp",
  "email": "[e-mail]",
  "phone": "[phone]",
  "tax_id": "US-12-3456789",
  "address": {
    "line1": "742 Evergreen Terrace",
    "line2": "Suite 100",
    "city": "Springfield",
    "state": "IL",
    "postal_code": "62701",
    "country": "US"
  },
  "deleted": false,
  "created": "2024-03-15T09:22:00.000Z"
}

id · string

Unique identifier for the customer. Prefixed with cus_.

object · string

String literal "customer".

name · string

Full legal or trade name of the customer.

email · string | null

Contact email address. Used when sending invoice emails directly to this customer.

phone · string | null

Phone number in any format.

tax_id · string | null

Tax identifier (VAT number, EIN, GSTIN, ABN, etc.). No format validation is applied — store whatever format the customer uses.

address · object

Billing address.

Show address fields

line1 · string | null

Street address, line 1.

line2 · string | null

Apartment, suite, unit, floor, etc.

city · string | null

City or locality.

state · string | null

State, province, or region.

postal_code · string | null

ZIP or postal code.

country · string | null

Two-letter ISO 3166-1 alpha-2 country code (e.g. "US").

deleted · boolean

true when the customer has been archived. Archived customers no longer appear in list results unless include_deleted=true is passed.

created · string

ISO 8601 datetime at which the customer was created.

---

Endpoints

GET /api/v1/customers — List customers

List all customers belonging to your workspace. Results are cursor-paginated, newest first.

Required scope: clients:read

Query parameters

query · string

Free-text search across name, email, and tax ID. Partial matches are supported.

cursor · string

Pagination cursor returned as next_cursor from a previous response. Omit to start from the beginning.

limit · integer

Maximum number of customers to return. Defaults to 20; maximum is 100.

include_deleted · boolean

When true, archived (soft-deleted) customers are included in results. Defaults to false.

Request

curl https://invoice.horizonpay.co/api/v1/customers?limit=2 \
  -H "Authorization: Bearer inv_live_..."

Response

{
  "data": [
    {
      "id": "cus_01hxyz1234567890abcdefghij",
      "object": "customer",
      "name": "Acme Corp",
      "email": "[e-mail]",
      "phone": "[phone]",
      "tax_id": "US-12-3456789",
      "address": {
        "line1": "742 Evergreen Terrace",
        "line2": "Suite 100",
        "city": "Springfield",
        "state": "IL",
        "postal_code": "62701",
        "country": "US"
      },
      "deleted": false,
      "created": "2024-03-15T09:22:00.000Z"
    },
    {
      "id": "cus_01hxyz9876543210zyxwvutsrq",
      "object": "customer",
      "name": "Globex Corporation",
      "email": null,
      "phone": null,
      "tax_id": null,
      "address": {
        "line1": null,
        "line2": null,
        "city": null,
        "state": null,
        "postal_code": null,
        "country": null
      },
      "deleted": false,
      "created": "2024-02-01T14:05:30.000Z"
    }
  ],
  "next_cursor": "cus_01hxyz9876543210zyxwvutsrq"
}

Pass the returned next_cursor value as the cursor query parameter on your next request to retrieve the following page. When next_cursor is null, you have reached the last page.

POST /api/v1/customers — Create a customer

Create a new customer. Only name is required; all other fields are optional.

Required scope: clients:write

Optionally send an Idempotency-Key header to safely retry the request without creating duplicates.

Body parameters

name · string · required

Full name or business name. Minimum 1 character.

email · string

Contact email. Must be a valid email address if provided.

phone · string

Phone number in any format.

tax_id · string

Tax identifier (VAT, EIN, GSTIN, ABN, etc.).

address · object

Billing address object.

Show address fields

line1 · string

Street address, line 1.

line2 · string

Suite, floor, unit, etc.

city · string

City or locality.

state · string

State, province, or region.

postal_code · string

ZIP or postal code.

country · string

Two-letter ISO 3166-1 alpha-2 country code (e.g. "US").

Request

curl https://invoice.horizonpay.co/api/v1/customers \
  -X POST \
  -H "Authorization: Bearer inv_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-acme-2024-03-15" \
  -d '{
    "name": "Acme Corp",
    "email": "[e-mail]",
    "phone": "[phone]",
    "tax_id": "US-12-3456789",
    "address": {
      "line1": "742 Evergreen Terrace",
      "line2": "Suite 100",
      "city": "Springfield",
      "state": "IL",
      "postal_code": "62701",
      "country": "US"
    }
  }'

Response 201 Created

{
  "data": {
    "id": "cus_01hxyz1234567890abcdefghij",
    "object": "customer",
    "name": "Acme Corp",
    "email": "[e-mail]",
    "phone": "[phone]",
    "tax_id": "US-12-3456789",
    "address": {
      "line1": "742 Evergreen Terrace",
      "line2": "Suite 100",
      "city": "Springfield",
      "state": "IL",
      "postal_code": "62701",
      "country": "US"
    },
    "deleted": false,
    "created": "2024-03-15T09:22:00.000Z"
  }
}

GET /api/v1/customers/:id — Retrieve a customer

Retrieve a single customer by ID.

Required scope: clients:read

The :id path parameter accepts either the cus_-prefixed public ID or the underlying UUID.

Request

curl https://invoice.horizonpay.co/api/v1/customers/cus_01hxyz1234567890abcdefghij \
  -H "Authorization: Bearer inv_live_..."

Response 200 OK

{
  "data": {
    "id": "cus_01hxyz1234567890abcdefghij",
    "object": "customer",
    "name": "Acme Corp",
    "email": "[e-mail]",
    "phone": "[phone]",
    "tax_id": "US-12-3456789",
    "address": {
      "line1": "742 Evergreen Terrace",
      "line2": "Suite 100",
      "city": "Springfield",
      "state": "IL",
      "postal_code": "62701",
      "country": "US"
    },
    "deleted": false,
    "created": "2024-03-15T09:22:00.000Z"
  }
}

PATCH /api/v1/customers/:id — Update a customer

Update one or more fields on an existing customer. Only the fields you include are changed; omitted fields retain their current values.

Required scope: clients:write

Body parameters

All fields are optional. Include only those you want to change.

name · string

New name for the customer.

email · string

New email address. Pass an empty string "" to clear the field.

phone · string

New phone number.

tax_id · string

New tax identifier.

address · object

Partial or full address update. Only keys you include are updated within the address object.

Show address fields

line1 · string

Street address, line 1.

line2 · string

Suite, floor, unit, etc.

city · string

City or locality.

state · string

State, province, or region.

postal_code · string

ZIP or postal code.

country · string

Two-letter ISO 3166-1 alpha-2 country code.

Request

curl https://invoice.horizonpay.co/api/v1/customers/cus_01hxyz1234567890abcdefghij \
  -X PATCH \
  -H "Authorization: Bearer inv_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[e-mail]",
    "address": {
      "line2": "Floor 3"
    }
  }'

Response 200 OK

{
  "data": {
    "id": "cus_01hxyz1234567890abcdefghij",
    "object": "customer",
    "name": "Acme Corp",
    "email": "[e-mail]",
    "phone": "[phone]",
    "tax_id": "US-12-3456789",
    "address": {
      "line1": "742 Evergreen Terrace",
      "line2": "Floor 3",
      "city": "Springfield",
      "state": "IL",
      "postal_code": "62701",
      "country": "US"
    },
    "deleted": false,
    "created": "2024-03-15T09:22:00.000Z"
  }
}

DELETE /api/v1/customers/:id — Archive a customer

Soft-delete (archive) a customer. The record is not destroyed — all historical invoices retain their customer references. The customer will no longer appear in list results unless you pass include_deleted=true.

Required scope: clients:write

This action mirrors Stripe’s deleted: true convention. Archived customers still appear when you retrieve them by ID or pass include_deleted=true to the list endpoint.

Request

curl https://invoice.horizonpay.co/api/v1/customers/cus_01hxyz1234567890abcdefghij \
  -X DELETE \
  -H "Authorization: Bearer inv_live_..."

Response 200 OK

The archived customer object is returned, with deleted: true.

{
  "data": {
    "id": "cus_01hxyz1234567890abcdefghij",
    "object": "customer",
    "name": "Acme Corp",
    "email": "[e-mail]",
    "phone": "[phone]",
    "tax_id": "US-12-3456789",
    "address": {
      "line1": "742 Evergreen Terrace",
      "line2": "Suite 100",
      "city": "Springfield",
      "state": "IL",
      "postal_code": "62701",
      "country": "US"
    },
    "deleted": true,
    "created": "2024-03-15T09:22:00.000Z"
  }
}

---

Error responses

Status	Cause
400 Bad Request	Validation failed — missing name, invalid email format, or unrecognised country code. The response body includes a detail field and a per-field errors array.
401 Unauthorized	Missing or invalid Authorization header.
403 Forbidden	The API key lacks the required scope (clients:read or clients:write).
404 Not Found	No customer with the given ID exists in your workspace.
409 Conflict	An Idempotency-Key was reused with a different request body.