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": "[email protected]",
  "phone": "+1-555-867-5309",
  "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"
}

string

Unique identifier for the customer. Prefixed with cus_.

string

String literal "customer".

string

Full legal or trade name of the customer.

string | null

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

string | null

Phone number in any format.

string | null

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

object

Billing address.

Show address fields

string | null

Street address, line 1.

string | null

Apartment, suite, unit, floor, etc.

string | null

City or locality.

string | null

State, province, or region.

string | null

ZIP or postal code.

string | null

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

boolean

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

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

string

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

string

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

integer

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

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": "[email protected]",
      "phone": "+1-555-867-5309",
      "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:writeOptionally send an Idempotency-Key header to safely retry the request without creating duplicates.

Body parameters

string

required

Full name or business name. Minimum 1 character.

string

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

string

Phone number in any format.

string

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

object

Billing address object.

Show address fields

string

Street address, line 1.

string

Suite, floor, unit, etc.

string

City or locality.

string

State, province, or region.

string

ZIP or postal code.

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": "[email protected]",
    "phone": "+1-555-867-5309",
    "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": "[email protected]",
    "phone": "+1-555-867-5309",
    "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:readThe :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": "[email protected]",
    "phone": "+1-555-867-5309",
    "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.

string

New name for the customer.

string

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

string

New phone number.

string

New tax identifier.

object

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

Show address fields

string

Street address, line 1.

string

Suite, floor, unit, etc.

string

City or locality.

string

State, province, or region.

string

ZIP or postal code.

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": "[email protected]",
    "address": {
      "line2": "Floor 3"
    }
  }'

Response `200 OK`

{
  "data": {
    "id": "cus_01hxyz1234567890abcdefghij",
    "object": "customer",
    "name": "Acme Corp",
    "email": "[email protected]",
    "phone": "+1-555-867-5309",
    "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:writeThis 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": "[email protected]",
    "phone": "+1-555-867-5309",
    "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.

Overview

Invoices

Customers & Catalog

Webhooks

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

Customers

The customer object

Endpoints

Query parameters

Request

Response

Body parameters

Request

Response `201 Created`

Request

Response `200 OK`

Body parameters

Request

Response `200 OK`

Request

Response `200 OK`

Error responses

​Customers

​The customer object

​Endpoints

​Query parameters

​Request

​Response

​Body parameters

​Request

​Response 201 Created

​Request

​Response 200 OK

​Body parameters

​Request

​Response 200 OK

​Request

​Response 200 OK

​Error responses

Customers

The customer object

Endpoints

Query parameters

Request

Response

Body parameters

Request

Response `201 Created`

Request

Response `200 OK`

Body parameters

Request

Response `200 OK`

Request

Response `200 OK`

Error responses