/customers

name: "Alternative Payments Customers"
description: >
  Alternative Payments customers and their users: customer fields and
  status, the customer/user relationship, MSP client onboarding, and the
  destructive archive operation that requires confirmation.
when_to_use: >-
  When listing, retrieving, creating, or archiving Alternative Payments customers, or managing the
  users attached to a customer. Use when: alternative payments customer, create customer, list
  customers, archive customer, customer users, add customer user, ap customer, customer
  onboarding, customer lookup, or alternativepayments customer.

Alternative Payments Customers Management

Overview

Customers are the foundational entity in Alternative Payments — every invoice, payment request, transaction, and payout traces back to a customer. For MSPs, a customer is typically a managed services client (a business you bill on a recurring or project basis). Each customer can have one or more **users** — the individual contacts at that business who receive invoices and pay them.

This skill covers the read + safe-write customer surface: listing, retrieving, and creating customers, adding users, and archiving (a destructive operation). There is no direct money-movement operation here.

Anti-triggers

• **The same client in the accounting ledger** — an Alternative Payments

customer is a billing target on the payment rail with no GL contact record; use `xero-contacts` or `qbo-customers`.

• **The same client in the CRM** — use `hubspot-companies` or

`salesbuildr-companies-contacts`.

• **Billing that customer** — use `alternative-payments-invoicing`.

Core Concepts

Customers and Users

| Entity | Description | MSP Example | |--------|-------------|-------------| | Customer | A business you bill | "Acme Corp" | | User | A contact at that business | "billing@acme.com" |

A customer is created first; users are then attached under `/customers/{id}/users`. Invoices and payment requests reference the customer.

Customer Status

| Status | Description | |--------|-------------| | `active` | Normal, billable customer (default) | | `archived` | Hidden from default lists; preserved for history |

Archiving is performed with `DELETE /customers/{id}` — it does **not** hard-delete the record. Treat it as destructive and confirm before running it.

Field Reference

Customer Fields

| Field | Type | Required | Description | |-------|------|----------|-------------| | `id` | string | System | Auto-generated unique identifier | | `name` | string | Yes | Business/company name | | `email` | string | No | Primary billing email | | `phone` | string | No | Primary phone number | | `external_id` | string | No | Your PSA/internal reference for cross-linking | | `address` | object | No | Billing address (line1, city, region, postal_code, country) | | `status` | string | Read-only | `active` or `archived` | | `created_at` | datetime | Read-only | Creation timestamp |

User Fields

| Field | Type | Required | Description | |-------|------|----------|-------------| | `id` | string | System | Auto-generated unique identifier | | `first_name` | string | Yes | User first name | | `last_name` | string | Yes | User last name | | `email` | string | Yes | User email address | | `phone` | string | No | User phone number |

API Patterns

All requests carry a bearer token (`Authorization: Bearer <token>`). See [Alternative Payments API Patterns](../api-patterns/SKILL.md) for the OAuth2 client-credentials token flow, the 5 req/sec rate limit, and cursor pagination.

List Customers

curl -s "https://public-api.alternativepayments.io/customers?limit=100" \
  -H "Authorization: Bearer ${TOKEN}"

Responses are cursor-paginated — items are in `data[]` with a `next_cursor` / `has_more` indicator. Pass `after=<cursor>` to fetch the next page.

curl -s "https://public-api.alternativepayments.io/customers?limit=100&after=cursor_abc" \
  -H "Authorization: Bearer ${TOKEN}"

Get a Single Customer

curl -s "https://public-api.alternativepayments.io/customers/${CUSTOMER_ID}" \
  -H "Authorization: Bearer ${TOKEN}"

Create a Customer

curl -s -X POST "https://public-api.alternativepayments.io/customers" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "email": "billing@acme.com",
    "phone": "+1-217-555-0123",
    "external_id": "MSP-ACME-001",
    "address": {
      "line1": "123 Main Street",
      "city": "Springfield",
      "region": "IL",
      "postal_code": "62704",
      "country": "US"
    }
  }'

List a Customer's Users

curl -s "https://public-api.alternativepayments.io/customers/${CUSTOMER_ID}/users?limit=100" \
  -H "Authorization: Bearer ${TOKEN}"

Add a User to a Customer

curl -s -X POST "https://public-api.alternativepayments.io/customers/${CUSTOMER_ID}/users" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Jordan",
    "last_name": "Lee",
    "email": "jordan.lee@acme.com",
    "phone": "+1-217-555-0144"
  }'

Archive a Customer (Destructive — Confirm First)

`DELETE /customers/{id}` archives the customer. **Always confirm with the user before running it**, and verify there are no outstanding invoices first.

curl -s -X DELETE "https://public-api.alternativepayments.io/customers/${CUSTOMER_ID}" \
  -H "Authorization: Bearer ${TOKEN}"

A `204 No Content` indicates success.

JavaScript Example

async function createCustomer(token, customer) {
  const res = await fetch('https://public-api.alternativepayments.io/customers', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(customer)
  });
  const text = await res.text();
  if (!res.ok) throw new Error(`Create custome