Skip to main content

Customers

A customer is the entity that purchases goods or services from a merchant. A customer may be a person or an organization. Every customer has a unique id referenced from other resources as customerId.

A customer is the main resource for most integrations — payment instruments, subscriptions, transactions, and invoices all hang off a customer.

Default payment instrument​

A customer may have a default payment instrument. The default is used:

  • To automatically pay subscription renewals.
  • For transaction requests where no specific paymentInstrumentId or token is provided in paymentInstruction.

A customer can hold multiple payment instruments. Only one is the default at any time. Setting a new default does not deactivate the previous one — it stays attached and chargeable by its ID.

For how payment instruments are created and how their state changes, see Payment instruments and Payment instrument lifecycle.

Relation to other resources​

ResourceRelation
Payment instrumentsA customer owns zero or more instruments. One can be default.
SubscriptionsA subscription always points at one customerId and one paymentInstrumentId.
TransactionsEvery transaction references a customerId.
InvoicesInvoices are addressed to a customerId.

Deleting a customer does not cancel their active subscriptions. Cancel subscriptions before deleting the customer record.

Customer CRUD​

Create a customer​

curl -X POST \
  "https://staging-api.payments.ai/v1/public-api/organizations/${ORGANIZATION_ID}/customers" \
  -H 'Content-Type: application/json' \
  -H "Authorization: ApiKey ${API_KEY}" \
  -d '{
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "[email protected]",
    "phoneNumber": "+1-555-0100",
    "language": "en",
    "address": {
      "country": "US",
      "address1": "123 Main St",
      "city": "Springfield",
      "region": "IL",
      "zip": "62701"
    }
  }'

Response returns the created Customer object with its assigned id. Store this ID — every later operation against this customer references it.

FieldRequiredNotes
firstNameRecommendedUsed on receipts and the hosted payment form.
lastNameRecommendedUsed on receipts and the hosted payment form.
emailRecommendedUsed for receipts, dunning emails, and as a fallback identifier.
phoneNumberOptionalE.164 format recommended.
languageOptionalISO 639-1 (en, es, etc.). Drives hosted-form language.
addressOptionalBilling address fallback when no transaction-level billingAddress is provided. The street field is address1 (the transaction endpoint uses address instead — they are not interchangeable).
metadataOptionalFree-form key-value object for merchant-specific data.

Retrieve a customer​

curl -X GET \
  "https://staging-api.payments.ai/v1/public-api/organizations/${ORGANIZATION_ID}/customers/${CUSTOMER_ID}" \
  -H "Authorization: ApiKey ${API_KEY}"

List customers​

curl -X GET \
  "https://staging-api.payments.ai/v1/public-api/organizations/${ORGANIZATION_ID}/customers?limit=20&offset=0" \
  -H "Authorization: ApiKey ${API_KEY}"

Supports limit/offset pagination and search (matches against name and email).

Update a customer​

curl -X PUT \
  "https://staging-api.payments.ai/v1/public-api/organizations/${ORGANIZATION_ID}/customers/${CUSTOMER_ID}" \
  -H 'Content-Type: application/json' \
  -H "Authorization: ApiKey ${API_KEY}" \
  -d '{
    "email": "[email protected]",
    "phoneNumber": "+1-555-0199"
  }'

The id of a customer cannot be changed. All other fields can be updated.

Delete a customer​

curl -X DELETE \
  "https://staging-api.payments.ai/v1/public-api/organizations/${ORGANIZATION_ID}/customers/${CUSTOMER_ID}" \
  -H "Authorization: ApiKey ${API_KEY}"

Deletion is soft — the customer record persists for audit and historical reporting (existing transactions and invoices keep resolving), but the customer can no longer be referenced from new operations. Active subscriptions on a deleted customer should be canceled first.

Lifecycle​

A customer has a simple lifecycle compared to a payment instrument:

  • Active — created via POST /customers, available for all operations.
  • Deleted — soft-deleted via DELETE /customers/{id}. Historical records remain; new operations referencing this customer are rejected.

There is no inactive or suspended state. To stop charging a customer, cancel their subscriptions and detach or delete their payment instruments.

Custom fields on customers​

You can attach merchant-specific structured data to a customer using custom fields. Define the schema once with POST /custom-fields (resource: customers), then populate per-customer values via the customer endpoint. See Custom fields.