Sign in

v1

latestOpenAPI 3.1.02026-08-042453938.9 KB
Customers

Create a customer

Create a customer. Just pass externalCustomerId (your user ID). Add onchainAddress later for on-chain billing.

Requires a secret key (sk_*) with at least the OPERATOR role.

post/v1/customers

Request body

externalCustomerIdstring

Your system customer ID. Required if onchainAddress is not provided.

onchainAddressstring

Smart account address. Required if externalCustomerId is not provided. Optional for ledger-only use.

emailstring email

Optional end-customer email. When set, invoice PDFs are emailed here automatically on issue, past-due, and payment.

isInternalboolean

Internal customer (visibility only, no billing)

metadataobject

Optional metadata

Example request

{
  "externalCustomerId": "user_789",
  "onchainAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f00000",
  "email": "billing@acme.com",
  "metadata": {
    "plan": "pro",
    "source": "signup"
  }
}

Response

Customer created successfully

idstring required

Internal customer ID

businessIdstring required

Business ID this customer belongs to

namestring nullable

Customer display name

externalCustomerIdstring nullable

Your system customer ID (null if created with onchainAddress only)

stripeCustomerIdstring nullable

Stripe customer ID linked via Connect or migration

onchainAddressstring nullable

Smart account address (null for internal customers)

emailstring email nullable

End-customer email used for invoice receipt delivery (null if not set)

isInternalboolean required

Internal customer (visibility only, no billing)

status'ACTIVE' | 'LOW_BALANCE' | 'PAUSED' required

Customer status

metadataobject nullable

Arbitrary metadata attached to the customer

createdAtstring date-time required
updatedAtstring date-time required
provisioningStatus'provisioned' | 'pending' | 'skipped' required

Provisioning outcome for the customer smart account

fundingRequiredboolean

True when the smart account exists but still needs funding before billing can proceed

_warningsstring[]

Non-fatal warnings generated while creating the customer

Example response

{
  "id": "cus_abc123def456",
  "businessId": "biz_abc123",
  "name": "Acme Logistics",
  "externalCustomerId": "user_789",
  "stripeCustomerId": "cus_StripeXYZ",
  "onchainAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f00000",
  "email": "billing@acme.com",
  "status": "ACTIVE",
  "metadata": {
    "plan": "pro",
    "source": "signup"
  },
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z",
  "provisioningStatus": "provisioned",
  "fundingRequired": true,
  "_warnings": [
    "External customer ID resembles a patient identifier; avoid storing PHI in identifiers."
  ]
}