id
required |
string (uuid)
|
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
creationTime
required |
string (date-time)
|
The date and time when this entity was created.
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
creatorId
required |
string (uuid)
|
The ID of the user who created this entity.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
lastModificationTime
required |
string (date-time)
|
The date and time when this entity was last modified.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
lastModifierId
required |
string (uuid)
|
The ID of the user who last modified this entity.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
isDeleted
required |
boolean
|
Indicates whether this entity has been deleted.
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
deleterId
required |
string (uuid)
|
The ID of the user who deleted this entity, if it is deleted.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
deletionTime
required |
string (date-time)
|
The date and time when this entity was deleted, if it is deleted.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
createdFromTemplateId
required |
string (uuid)
|
The template this record was created from, or `null` for one started blank. Set by the
create-from-template path and by the add/edit page's Load Template action when the record is
saved.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
name
required |
string
|
Gets or sets the name of the customer. Unique within the owning merchant, compared
case-insensitively.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
displayName
required |
string
|
An optional human-readable label for the customer that is deliberately not unique. Null when
the customer carries no separate label, in which case `name` is what merchants
see wherever customers are listed.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
concurrencyStamp
required |
string
|
Gets or sets the concurrency stamp used for optimistic concurrency control.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
tenantId
required |
string (uuid)
|
Gets the tenant identifier for multi-tenancy isolation.
nullableread only
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
merchantId
required |
string (uuid)
|
Gets or sets the identifier of the merchant that owns this customer.
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
isActive
required |
boolean
|
Gets or sets a value indicating whether this customer is active.
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
legacyNumber
required |
integer (int64)
|
Gets or sets the customer's legacy numeric key, the integer identifier the v1 API resolves
customers by. Server-owned: stamped at create and ignored on every inbound payload. Null on
customers created before the field existed and not yet back-filled by the v1 data migration.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
merchantAssignedId
required |
string
|
An optional identifier the merchant assigns to the customer as a friendly reference, distinct
from the system Guid `Id` and the server-owned `legacyNumber`. Surfaces
the v1 API's `CustomerId` field.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
contactDetail
required |
CustomerContactDetail
CustomerContactDetail |
Gets or sets the customer's contact details (email, phone, address).
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
Fields of CustomerContactDetail:
| Field |
Type |
Description |
|---|
primaryContactName
required |
string
|
nullablemax length 100
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| emailAddress
required |
string
|
The contact's email address. Optional. A value that is not blank must be a valid email address.
Conditional: When EmailAddress is not empty. Must be a valid email.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| phone
required |
string
|
The contact's phone number. Optional. A value that is not empty must be a phone number: digits,
with an optional leading `+` and country code, optional parentheses around the area code,
and a space, hyphen or period between groups. Letters, including an extension such as
`x123`, are rejected.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| fax
required |
string
|
The contact's fax number. Optional. Follows the same rule as the phone number.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| companyUrl
required |
string
|
The company's website address. Optional. A value sent without a scheme, such as
`www.example.com`, is stored with `https://` added. A value that starts with
`http://` or `https://` is stored exactly as sent. Any other scheme, and text that is
not a website address, is rejected.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| addresses
required |
array of CustomerAddress
array of CustomerAddress |
The customer's addresses on file. Optional: omit the member, send an empty array, or send
null to record a customer with no address on file. When one or more entries are supplied,
exactly one must be flagged `isDefault`, and every entry must carry `address1`,
`city`, `state` and `zip`.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
This body has no documented fields. |
tags
required |
array of EntityTag
array of EntityTag |
Gets or sets the collection of tags used to categorize or label this customer.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
Fields of each EntityTag:
| Field |
Type |
Description |
|---|
name
required |
string
|
nullablemin length 0max length 50
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| value
required |
string
|
nullablemin length 0max length 150
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
This body has no documented fields. |
storedPaymentMethods
required |
array of CustomerStoredPaymentMethod
array of CustomerStoredPaymentMethod |
Gets or sets the customer's stored payment methods for recurring or future transactions.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
Fields of each CustomerStoredPaymentMethod:
| Field |
Type |
Description |
|---|
id
required |
string (uuid)
|
read only
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| paymentMethodType
required |
CustomerStoredPaymentMethodType
CustomerStoredPaymentMethodType |
Specifies the type of a stored payment method associated with a customer.
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| paymentTokenId
required |
string (uuid)
|
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| cardData
required |
CardData
CardData |
Required: When PaymentMethodType == Card.
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| checkData
required |
CheckData
CheckData |
Required: When PaymentMethodType == Check.
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| isDefault
required |
boolean
|
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| displayName
required |
string
|
nullableread only
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| isDeleted
required |
boolean
|
Indicates whether this entity has been deleted.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| customName
required |
string
|
Optional user-defined name for this stored payment method (e.g., "Marriott Chase",
"Bank of America Checkcard"). When set, takes priority over the computed display name.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| initialSchemeTransactionId
required |
string
|
The initial (first-in-series) network / scheme transaction id captured from the processor's
authorization response on the cardholder-initiated credential-on-file transaction that stored
this credential. Lets any later transaction (CIT-COF or MIT, any card brand) resolve and echo
the original network transaction id from just the stored token / payment method, without
depending on a StoredCredentialConsent lookup.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| lastSchemeTransactionId
required |
string
|
The most-recent-in-series network / scheme transaction id. At tokenization this equals
`initialSchemeTransactionId`. Card-network rules (Visa 11.1.5, Mastercard 13.1.1)
allow the most recent value in a series to be sent when the original is unavailable, so a later
story can advance this on each subsequent authorization response without losing the first-in-
series anchor. Nullable / non-sensitive as for `initialSchemeTransactionId`.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| schemeTransactionIdBrand
required |
string
|
The card brand at the moment the network transaction id was captured (e.g. "Visa",
"Mastercard", "Discover", "Amex"). Retained because a co-branded card can switch networks
after storage; Mastercard's AltNetTranID handling requires the brand-at-capture to detect the
case where a stored Visa id must be sent in a Mastercard field. Emitting AltNetTranID is out of
scope here: this only preserves the data so the downstream echo work is not precluded.
Nullable / non-sensitive.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| schemeTransactionIdProcessor
required |
string
|
The processor the network transaction id originated from ("tsys" / "fiserv"). The two
processors' response formats differ (TSYS a single 15-char Transaction Identifier; Fiserv
per-brand, whose Visa value can exceed 15 chars including the trailing Validation Code), so the
id is stored opaquely and tagged with its originating processor. Nullable / non-sensitive.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| publicReference
required |
string
|
The externally-emitted, chargeable `PublicReference` of the backing `PaymentToken`
(the opaque `pt_`-prefixed handle) captured when this stored method was minted. Persisted
here so the tokenize-on-payment path can surface it on the transaction response / webhook
without re-reading the token, and so a later charge can round-trip the merchant-facing handle.
Distinct from `paymentTokenId`, which is the internal vault Guid (PAN-correlated,
never emitted). May be `null` on a stored method created before this field existed, until
a one-time platform backfill copies the backing token's handle onto it; the backfill only ever
fills a null and never rewrites an assigned handle. Non-sensitive (an opaque random handle,
not a PAN).
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| origin
required |
StoredPaymentMethodOrigin
StoredPaymentMethodOrigin |
The surface / add-channel this stored payment method was captured through (manual admin,
hosted payment page, virtual terminal, or API). Stamped once at creation and not changed
afterward.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
Unknown |
The add-channel was not recorded. Assigned to methods that predate this field (materialized from a null value) and to any path that did not classify its origin. | ManualAdmin |
Added by an operator through a Customer admin surface that mints the stored method on the customer document directly (the customer edit form's payment-methods dialog, and the create-customer / create-contract-from-transaction dialogs). Note: the contract add-payment dialog submits through the HTTP add endpoint and is therefore recorded as Api, since origin on that boundary is server-authoritative and cannot be caller-supplied. | HostedPaymentPage |
Vaulted from a hosted payment page: either tokenize-on-payment or the direct ACH vault flow. | VirtualTerminal |
Vaulted from a Virtual Terminal save-on-payment. | Api |
Added through the HTTP add-stored-payment-method endpoint. Covers external API token registration and any in-process operator surface that submits through that same gated endpoint (e.g. the contract add-payment dialog): origin on this boundary is stamped server-side and is never caller-supplied. |
| readerTokenFingerprint
required |
string
|
Dedupe fingerprint for a reader-token-backed (PAN-less) stored method: a one-way SHA-256
digest of the processor reader token that this method's backing vault token carries. Set
only for the reader-token shape (decrypt-and-forward processors such as MagTek DAF, where
the gateway never sees the PAN); `null` for every PAN- or account-backed method.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| checkFingerprint
required |
string
|
Dedupe fingerprint for a check / ACH stored method: a keyed, non-reversible HMAC-SHA-256
digest of the routing number combined with the account number's last four digits. Set only
for the Check shape; `null` for card and reader-token methods.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
This body has no documented fields. |
contracts
required |
array of Contract
array of Contract |
Gets or sets the recurring billing contracts associated with this customer.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
Fields of each Contract:
| Field |
Type |
Description |
|---|
id
required |
string (uuid)
|
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| name
required |
string
|
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| notes
required |
array of EntityNote
array of EntityNote |
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| tags
required |
array of EntityTag
array of EntityTag |
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| customerId
required |
string (uuid)
|
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| legacyNumber
required |
integer (int64)
|
The contract's legacy numeric key, as used by the v1 API where contracts are identified by an
integer rather than a Guid. Server-owned: stamped once at create from a tenant-scoped counter
and never settable from an inbound payload.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| customFields
required |
array of ContractCustomField
array of ContractCustomField |
The merchant-defined custom field values carried on this contract, or `null`
when it carries none.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| perBillInvoice
required |
ContractPerBillInvoice
ContractPerBillInvoice |
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| thresholds
required |
ContractThresholds
ContractThresholds |
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| aggregates
required |
ContractAggregates
ContractAggregates |
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| schedule
required |
ContractSchedule
ContractSchedule |
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| payMethod
required |
ContractPayMethod
ContractPayMethod |
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| emailNotifications
required |
ContractEmailNotifications
ContractEmailNotifications |
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| isActive
required |
boolean
|
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| planId
required |
string (uuid)
|
The reusable plan this contract subscribes to for its price, or `null` when
the contract carries its own inline amount.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| trialEndDate
required |
string (date-time)
|
The calendar day the contract's trial period ends, in UTC, or `null` when the
contract has no trial. Nothing is charged before this day: the first charge falls on it (or
on the schedule's first occurrence after it) at the full contract amount.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| priceChangedAt
required |
string (date-time)
|
When an operator last changed what this contract charges per cycle (the plan it subscribes
to, or its inline amount), in UTC, or `null` when that has never happened
since the field existed. Server owned: stamped by the contract update path, never settable
from an inbound payload.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| deactivationReason
required |
ContractDeactivationReason
ContractDeactivationReason |
Describes why this contract was deactivated. Null when the contract is active
or was never deactivated by the billing engine. Set automatically by the
recurring billing manager and cleared when the contract is reactivated.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
Suspended |
Suspended by the billing engine after consecutive failures exceeded the maxFailCount threshold. | MaxPaymentsReached |
Total execution count (successful + failed) reached maxNumPayments. | MaxSuccessfulBillsReached |
Successful execution count reached maxSuccessfulBills. | MaxAmountReached |
Cumulative amount billed reached maxAmount. | ScheduleExhausted |
The recurrence schedule produced no further occurrences: either the until end date was reached or the recurrence count was exhausted. | Manual |
Manually deactivated by an operator via the UI or API. | CancelledByCardholder |
Cancelled by the cardholder themselves, from the link in an upcoming-charge reminder, with no operator involved. | Paused |
Paused on purpose by an operator, to be resumed later: either by hand, or automatically by the daily billing run once the contract's expected resume date has passed. A pause is a voluntary stop, which is what separates it from Suspended (the billing engine gave up after consecutive failures) and from Manual (deactivated with no intention to resume). The pause itself is described by the contract's pause fields (reason, paused date, expected resume date), which are cleared when the contract resumes. |
| pauseReason
required |
string
|
Why an operator paused this contract, or `null` when it is not paused. Server
owned: written by the pause operation and cleared by every resume, never settable from an
inbound payload.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| pausedDate
required |
string (date-time)
|
When the contract was paused, in UTC, or `null` when it is not paused. Server
owned, stamped by the pause operation and cleared on resume.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| expectedResumeDate
required |
string (date-time)
|
The calendar day, in UTC, on which the daily billing run resumes this contract on its own, or
`null` for a pause with no end date, which only an operator can resume. A
calendar date compared as written, never timezone-converted, the same rule
`trialEndDate` follows: the run that finds this day at or before today resumes
the contract and projects its next charge from that moment.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| convenienceFeeWaived
required |
boolean
|
Whether the cardholder enrolled in this contract on terms that disclosed no convenience fee,
so no scheduled charge under it may carry one. `null` or `false`
means the fee is decided at each charge from the merchant's live configuration, as it always
has been. Server owned: stamped once when a Hosted Payment Page session carrying the
`suppress_convenience_fee` directive creates the contract, never settable from an inbound
payload.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| upcomingChargeReminderSentForRun
required |
string (date-time)
|
The scheduled run, in UTC, that the pre-charge reminder was last sent for, or
`null` when no reminder has been sent. Server owned: written only by the
recurring billing run after the reminder email is queued, never settable from an inbound
payload.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| description
required |
string
|
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| creationTime
required |
string (date-time)
|
The date and time when this entity was created.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| creatorId
required |
string (uuid)
|
The ID of the user who created this entity.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| lastModificationTime
required |
string (date-time)
|
The date and time when this entity was last modified.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| lastModifierId
required |
string (uuid)
|
The ID of the user who last modified this entity.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| isDeleted
required |
boolean
|
Indicates whether this entity has been deleted.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| deleterId
required |
string (uuid)
|
The ID of the user who deleted this entity, if it is deleted.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| deletionTime
required |
string (date-time)
|
The date and time when this entity was deleted, if it is deleted.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| concurrencyStamp
required |
string
|
Optimistic-concurrency stamp for the contract, checked independently of the customer that
holds it. A null stamp means "no concurrency check" until the contract is next updated, which
stamps it going forward.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
This body has no documented fields. |
entityVersion
required |
integer (int32)
|
Gets the entity version, incremented on each modification for optimistic concurrency.
read only
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
extraProperties
required |
object
|
Gets the extra properties dictionary for extensible data storage.
nullableread only
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
notes
required |
array of EntityNote
array of EntityNote |
Gets or sets operational notes attached to the customer.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
Fields of each EntityNote:
| Field |
Type |
Description |
|---|
id
required |
string (uuid)
|
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| enteredBy
required |
string (uuid)
|
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| timestamp
required |
string (date-time)
|
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| enteredByName
required |
string
|
Denormalized display name of the user who created the note.
Populated at creation time from `ICurrentUser` to avoid N+1 lookups when rendering.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| content
required |
string
|
nullablemin length 0max length 1000
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
This body has no documented fields. |