Accept payments

Customers

Create and manage customer records. Each payment must reference a customer.

4 min read

Overview

The Customer object represents a payer in your system. Every Payment, Invoice, and Subscription references a customer id. Customers are scoped to your merchant account — email addresses must be unique within your tenant.

Create a customer

POST /api/v1/customers

curl -X POST https://api.paymenthooks.com/v1/customers \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_test_..." \
  -d '{"name":"Jane Doe","email":"[email protected]","country":"US"}'

Parameters

POST /v1/customers request body

Field	Type	Description
`name`	`string`	Customer's full name or business name. 1–255 chars.
`email`	`string`	A unique email per merchant. Returns `409 DUPLICATE_EMAIL` on conflict.
`phone`	`string`	Contact phone number. Max 50 chars.
`country`	`string` Default: `merchant.country`	ISO 3166-1 alpha-2 country code (e.g. `US`, `GB`, `IN`). Defaults to merchant's country.
`metadata`	`object`	String→string key-value pairs for your internal reference.

Endpoints & Responses

All routes are tenant-scoped. totalSpend and paymentCount are computed server-side and update automatically as payments succeed.

POST/v1/customersCreate a customer

Request Payload

{
  "name": "Jane Doe",
  "email": "[email protected]",
  "phone": "+15551234567",
  "country": "US",
  "metadata": { "crmId": "hubspot-90827" }
}

Response

{
  "data": {
    "id": "cus_8k3m2n4p6q",
    "merchantId": "mer_abc123",
    "name": "Jane Doe",
    "email": "[email protected]",
    "phone": "+15551234567",
    "country": "US",
    "currency": "USD",
    "status": "active",
    "totalSpend": 0,
    "paymentCount": 0,
    "metadata": { "crmId": "hubspot-90827" },
    "createdAt": "2026-05-16T10:30:00.000Z",
    "updatedAt": "2026-05-16T10:30:00.000Z"
  },
  "error": null
}

GET/v1/customers?page=1&pageSize=10List customers

Response

{
  "data": [
    {
      "id": "cus_8k3m2n4p6q",
      "name": "Jane Doe",
      "email": "[email protected]",
      "country": "US",
      "totalSpend": 12450,
      "paymentCount": 3,
      "status": "active"
    }
  ],
  "meta": { "total": 42, "page": 1, "pageSize": 10 },
  "error": null
}

GET/v1/customers/:idRetrieve a customer

Response

{
  "data": {
    "id": "cus_8k3m2n4p6q",
    "merchantId": "mer_abc123",
    "name": "Jane Doe",
    "email": "[email protected]",
    "phone": "+15551234567",
    "country": "US",
    "status": "active",
    "totalSpend": 12450,
    "paymentCount": 3,
    "metadata": {},
    "createdAt": "2026-05-16T10:30:00.000Z",
    "updatedAt": "2026-05-16T11:00:00.000Z"
  },
  "error": null
}

PUT/v1/customers/:idUpdate a customer

Request Payload

{
  "name": "Jane Doe-Smith",
  "phone": "+15559876543",
  "metadata": { "crmId": "hubspot-90827", "vip": "true" }
}

Response

{
  "data": {
    "id": "cus_8k3m2n4p6q",
    "name": "Jane Doe-Smith",
    "email": "[email protected]",
    "phone": "+15559876543",
    "metadata": { "crmId": "hubspot-90827", "vip": "true" },
    "updatedAt": "2026-05-16T12:00:00.000Z"
  },
  "error": null
}

DELETE/v1/customers/:idDelete a customer

Response

{
  "data": { "deleted": true, "id": "cus_8k3m2n4p6q" },
  "error": null
}

Addresses

A customer can have multiple addresses (typically billing and shipping). These are used by invoice line items, tax calculations, and to prefill checkout sessions.

POST/v1/customers/:id/addressesAdd an address to a customer

Request Payload

{
  "type": "billing",
  "line1": "123 Market Street",
  "line2": "Suite 400",
  "city": "San Francisco",
  "state": "CA",
  "postalCode": "94103",
  "country": "US"
}

Response

{
  "data": {
    "id": "addr_5r7t9u1w3x",
    "customer_id": "cus_8k3m2n4p6q",
    "address_type": "billing",
    "region_code": "CA",
    "city": "San Francisco",
    "postal_code": "94103",
    "address_line1": "123 Market Street",
    "address_line2": "Suite 400",
    "country_iso2": "US",
    "country_name": "US",
    "created_at": "2026-05-16T10:30:00.000Z"
  },
  "error": null
}

GET/v1/customers/:id/addressesList addresses for a customer

Response

{
  "data": [/* address objects */],
  "error": null
}

DELETE/v1/customers/:id/addresses/:addressIdDelete an address

Response

{
  "data": { "deleted": true },
  "error": null
}

Tax IDs

Tax IDs feed the tax engine so invoices can apply the right exemption. The type field must be one of the supported values below — anything else returns 400 VALIDATION_ERROR.

Supported tax-id typestext

eu_vat, us_ein, gb_vat, au_abn, in_gst, ca_gst

POST/v1/customers/:id/tax-idsAdd a tax ID to a customer

Request Payload

{
  "type": "eu_vat",
  "value": "DE123456789"
}

Response

{
  "data": {
    "id": "txi_4d6f8a0b2c",
    "customerId": "cus_8k3m2n4p6q",
    "type": "eu_vat",
    "value": "DE123456789",
    "createdAt": "2026-05-16T10:30:00.000Z"
  },
  "error": null
}

EU VAT validation (format check + VIES lookup) runs asynchronously — the customer.updated webhook reports the verification outcome.

Accept payments

Customers

Create and manage customer records. Each payment must reference a customer.

4 min read

Overview

Create a customer

POST /api/v1/customers

curl -X POST https://api.paymenthooks.com/v1/customers \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_test_..." \
  -d '{"name":"Jane Doe","email":"[email protected]","country":"US"}'

Parameters

POST /v1/customers request body

Field	Type	Description
`name`	`string`	Customer's full name or business name. 1–255 chars.
`email`	`string`	A unique email per merchant. Returns `409 DUPLICATE_EMAIL` on conflict.
`phone`	`string`	Contact phone number. Max 50 chars.
`country`	`string` Default: `merchant.country`	ISO 3166-1 alpha-2 country code (e.g. `US`, `GB`, `IN`). Defaults to merchant's country.
`metadata`	`object`	String→string key-value pairs for your internal reference.

Endpoints & Responses

All routes are tenant-scoped. totalSpend and paymentCount are computed server-side and update automatically as payments succeed.

POST/v1/customersCreate a customer

Request Payload

{
  "name": "Jane Doe",
  "email": "[email protected]",
  "phone": "+15551234567",
  "country": "US",
  "metadata": { "crmId": "hubspot-90827" }
}

Response

{
  "data": {
    "id": "cus_8k3m2n4p6q",
    "merchantId": "mer_abc123",
    "name": "Jane Doe",
    "email": "[email protected]",
    "phone": "+15551234567",
    "country": "US",
    "currency": "USD",
    "status": "active",
    "totalSpend": 0,
    "paymentCount": 0,
    "metadata": { "crmId": "hubspot-90827" },
    "createdAt": "2026-05-16T10:30:00.000Z",
    "updatedAt": "2026-05-16T10:30:00.000Z"
  },
  "error": null
}

GET/v1/customers?page=1&pageSize=10List customers

Response

{
  "data": [
    {
      "id": "cus_8k3m2n4p6q",
      "name": "Jane Doe",
      "email": "[email protected]",
      "country": "US",
      "totalSpend": 12450,
      "paymentCount": 3,
      "status": "active"
    }
  ],
  "meta": { "total": 42, "page": 1, "pageSize": 10 },
  "error": null
}

GET/v1/customers/:idRetrieve a customer

Response

{
  "data": {
    "id": "cus_8k3m2n4p6q",
    "merchantId": "mer_abc123",
    "name": "Jane Doe",
    "email": "[email protected]",
    "phone": "+15551234567",
    "country": "US",
    "status": "active",
    "totalSpend": 12450,
    "paymentCount": 3,
    "metadata": {},
    "createdAt": "2026-05-16T10:30:00.000Z",
    "updatedAt": "2026-05-16T11:00:00.000Z"
  },
  "error": null
}

PUT/v1/customers/:idUpdate a customer

Request Payload

{
  "name": "Jane Doe-Smith",
  "phone": "+15559876543",
  "metadata": { "crmId": "hubspot-90827", "vip": "true" }
}

Response

{
  "data": {
    "id": "cus_8k3m2n4p6q",
    "name": "Jane Doe-Smith",
    "email": "[email protected]",
    "phone": "+15559876543",
    "metadata": { "crmId": "hubspot-90827", "vip": "true" },
    "updatedAt": "2026-05-16T12:00:00.000Z"
  },
  "error": null
}

DELETE/v1/customers/:idDelete a customer

Response

{
  "data": { "deleted": true, "id": "cus_8k3m2n4p6q" },
  "error": null
}

Addresses

A customer can have multiple addresses (typically billing and shipping). These are used by invoice line items, tax calculations, and to prefill checkout sessions.

POST/v1/customers/:id/addressesAdd an address to a customer

Request Payload

{
  "type": "billing",
  "line1": "123 Market Street",
  "line2": "Suite 400",
  "city": "San Francisco",
  "state": "CA",
  "postalCode": "94103",
  "country": "US"
}

Response

{
  "data": {
    "id": "addr_5r7t9u1w3x",
    "customer_id": "cus_8k3m2n4p6q",
    "address_type": "billing",
    "region_code": "CA",
    "city": "San Francisco",
    "postal_code": "94103",
    "address_line1": "123 Market Street",
    "address_line2": "Suite 400",
    "country_iso2": "US",
    "country_name": "US",
    "created_at": "2026-05-16T10:30:00.000Z"
  },
  "error": null
}

GET/v1/customers/:id/addressesList addresses for a customer

Response

{
  "data": [/* address objects */],
  "error": null
}

DELETE/v1/customers/:id/addresses/:addressIdDelete an address

Response

{
  "data": { "deleted": true },
  "error": null
}

Tax IDs

Tax IDs feed the tax engine so invoices can apply the right exemption. The type field must be one of the supported values below — anything else returns 400 VALIDATION_ERROR.

Supported tax-id typestext

eu_vat, us_ein, gb_vat, au_abn, in_gst, ca_gst

POST/v1/customers/:id/tax-idsAdd a tax ID to a customer

Request Payload

{
  "type": "eu_vat",
  "value": "DE123456789"
}

Response

{
  "data": {
    "id": "txi_4d6f8a0b2c",
    "customerId": "cus_8k3m2n4p6q",
    "type": "eu_vat",
    "value": "DE123456789",
    "createdAt": "2026-05-16T10:30:00.000Z"
  },
  "error": null
}

EU VAT validation (format check + VIES lookup) runs asynchronously — the customer.updated webhook reports the verification outcome.