Customers API

Manage customers, their addresses, and business profiles. Each customer can have multiple addresses (billing, shipping) and business profiles for B2B tax handling.

GET/api/v1/payment/customers/

List all customers for the authenticated merchant. Supports search, has_subscription, ordering, page, page_size query params.

POST/api/v1/payment/customers/

Create a new customer. Body: { email, name, phone? }

GET/api/v1/payment/customers/{id}/

Get customer detail including orders, subscriptions, and invoices.

PATCH/api/v1/payment/customers/{id}/

Update customer details. Body: { email?, name?, phone? }

GET/api/v1/payment/customer-addresses/

List customer addresses. Filter by customer_id, address_type query params.

POST/api/v1/payment/customer-addresses/

Create an address. Body: { customer_id, address_type, line1, line2?, city, state?, postal_code?, country, is_default? }

PATCH/api/v1/payment/customer-addresses/{id}/

Update an address. Any field can be partially updated.

DELETE/api/v1/payment/customer-addresses/{id}/

Delete an address.

GET/api/v1/payment/customer-businesses/

List customer business profiles. Filter by customer_id.

POST/api/v1/payment/customer-businesses/

Create a business profile. Body: { customer_id, company_name, tax_id?, tax_id_type?, website?, is_default? }

PATCH/api/v1/payment/customer-businesses/{id}/

Update a business profile.

DELETE/api/v1/payment/customer-businesses/{id}/

Delete a business profile.

Customer Object

{
  "id": "uuid",
  "email": "customer@example.com",
  "name": "Jane Doe",
  "phone": "+1234567890",
  "orders_count": 5,
  "total_spent": "499.99",
  "currency": "USD",
  "has_active_subscription": true,
  "subscription_status": "active",
  "created_at": "2026-01-15T10:00:00Z",
  "last_order_at": "2026-02-10T14:30:00Z"
}

Address Object

{
  "id": "uuid",
  "customer": "uuid",
  "address_type": "billing",  // billing | shipping | other
  "line1": "123 Main St",
  "line2": "Suite 100",
  "city": "San Francisco",
  "state": "CA",
  "postal_code": "94105",
  "country": "US",  // ISO 3166-1 alpha-2
  "is_default": true,
  "created_at": "2026-01-15T10:00:00Z"
}

Business Profile Object

{
  "id": "uuid",
  "customer": "uuid",
  "company_name": "Acme Corp",
  "tax_id": "DE123456789",
  "tax_id_type": "eu_vat",  // eu_vat | us_ein | gb_vat | in_gst
  "website": "https://acme.com",
  "is_default": true,
  "created_at": "2026-01-15T10:00:00Z"
}