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 by your internal customer code. Returns the existing AccruPay customer record, or null if no customer with that code exists yet.

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

Arguments

Argument	Type	Required	Description
selector	MerchantCustomerSelector	Yes	Customer lookup input

MerchantCustomerSelector fields

Field	Type	Required	Description
merchantInternalCustomerCode	String	Yes	Your internal identifier for the customer

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!) {
  merchantApiCustomerCreate(data: $data) {
    id
    merchantInternalCustomerCode
    firstName
    lastName
    email
    phone
    createdAt
    updatedAt
  }
}

Arguments

Argument	Type	Required	Description
data	MerchantCustomerCreateSchema	Yes	Customer data

MerchantCustomerCreateSchema fields

Field	Type	Required	Description
merchantInternalCustomerCode	String	Yes	Your unique customer identifier — must 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

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	DateTime	Record creation timestamp
updatedAt	DateTime	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 returns a VALIDATION_ERROR.

---

Related

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