Customers

A customer record in AccruPay links your internal customer identifier to AccruPay's customer UUID. Customer records are created lazily — AccruPay creates one the first time you reference a merchantInternalCustomerCode in a transaction or payment plan.

You can also create or resolve customer records explicitly using the operations below.

---

merchantApiCustomerResolve

Look up a customer against a configured provider. Returns a non-null MerchantCustomer — the operation throws if no matching customer is found (it does not return null).

query ResolveCustomer(
  $selector: MerchantCustomerSelector!
  $merchantTransactionProviderId: String
) {
  merchantApiCustomerResolve(
    selector: $selector
    merchantTransactionProviderId: $merchantTransactionProviderId
  ) {
    id
    merchantInternalCustomerCode
    firstName
    lastName
    email
    phone
    createdAt
    updatedAt
  }
}

Arguments

Argument	Type	Required	Description
selector	MerchantCustomerSelector	Yes	Customer lookup input
merchantTransactionProviderId	String	No	Target a specific configured provider by its internal ID. Required if you have multiple providers.
transactionProvider	TRANSACTION_PROVIDER	No	Select provider by enum. Alternative to merchantTransactionProviderId.

MerchantCustomerSelector fields

Field	Type	Required	Description
merchantInternalCustomerCode	String	Yes	Your internal identifier for the customer
id	String	No	AccruPay customer ID
providerCode	String	No	Customer code on the transaction provider
resolutionStrategy	CUSTOMER_RESOLUTION_STRATEGY	No	How to resolve the customer: AUTO, MATCH_OR_CREATE, MATCH_OR_FAIL, STRICT. See Enums.

Example variables

{
  "selector": {
    "merchantInternalCustomerCode": "customer-123"
  }
}

---

merchantApiCustomerCreate

Explicitly create a customer record. Use this when you want to register a customer before their first transaction.

mutation CreateCustomer(
  $data: MerchantCustomerCreateSchema!
  $merchantTransactionProviderId: String
) {
  merchantApiCustomerCreate(
    data: $data
    merchantTransactionProviderId: $merchantTransactionProviderId
  ) {
    id
    merchantInternalCustomerCode
    firstName
    lastName
    email
    phone
    createdAt
    updatedAt
  }
}

Arguments

Argument	Type	Required	Description
data	MerchantCustomerCreateSchema	Yes	Customer data
merchantTransactionProviderId	String	No	Target a specific configured provider by its internal ID. Required if you have multiple providers.
transactionProvider	TRANSACTION_PROVIDER	No	Select provider by enum. Alternative to merchantTransactionProviderId.

MerchantCustomerCreateSchema fields

Field	Type	Required	Description
merchantInternalCustomerCode	String	No	Your customer identifier — should be stable and unique within your merchant account
firstName	String	No	Customer first name
lastName	String	No	Customer last name
email	String	No	Customer email address
phone	String	No	Customer phone number
addressLine1	String	No	Street address line 1
addressLine2	String	No	Street address line 2
addressCity	String	No	City
addressState	String	No	State or province
addressPostalCode	String	No	Postal / ZIP code
addressCountry	String	No	ISO 3166-1 alpha-2 country code

Example

mutation {
  merchantApiCustomerCreate(
    data: {
      merchantInternalCustomerCode: "customer-123"
      firstName: "Jane"
      lastName: "Smith"
      email: "jane@example.com"
    }
  ) {
    id
    merchantInternalCustomerCode
  }
}

---

Customer return shape

Both operations return the same customer object.

Field	Type	Description
id	String	AccruPay customer UUID
merchantInternalCustomerCode	String	Your customer identifier
firstName	String	First name; null if not set
lastName	String	Last name; null if not set
email	String	Email; null if not set
phone	String	Phone; null if not set
createdAt	DateTimeISO	Record creation timestamp
updatedAt	DateTimeISO	Last update timestamp

---

Notes

• merchantInternalCustomerCode is your source-of-truth link between AccruPay and your own database. Choose a stable identifier such as your database primary key or UUID — do not use mutable values like email addresses.
• Payment methods and payment plans are associated with customers via merchantInternalCustomerCode. A customer record is automatically created the first time that code appears in a transaction.
• If you call merchantApiCustomerCreate with a code that already exists, the API fails with a business-rule error (a namespaced @domain/REASON AppError key in extensions.code). See Errors.

---

Related

• Payment Methods — stored payment methods are linked to customers
• Payment Plans — plans reference customers via merchantInternalCustomerCode
• Errors