Customers

SDK stub — use GraphQL directly

The @accrupay/node customers service currently exports GraphQL fragments only. There are no query functions available on accrupay.customers.*. Use the GraphQL API directly with a raw GraphQL client until full SDK support is added.

Concepts

Resolve a customer

Resolves a customer record against a configured provider. merchantApiCustomerResolve is a query and returns a non-null MerchantCustomer (it throws if no match is found — it does not return null).

Selector type

type MerchantCustomerSelector = {
  merchantInternalCustomerCode: string; // required
  id?: string;                          // AccruPay customer ID
  providerCode?: string;                // customer code on the transaction provider
  resolutionStrategy?: CUSTOMER_RESOLUTION_STRATEGY;
};

The operation also requires a provider — pass merchantTransactionProviderId or transactionProvider.

Equivalent GraphQL operation (send directly via your HTTP client):

query MerchantApiCustomerResolve(
  $selector: MerchantCustomerSelector!
  $merchantTransactionProviderId: String
) {
  merchantApiCustomerResolve(
    selector: $selector
    merchantTransactionProviderId: $merchantTransactionProviderId
  ) {
    id
    merchantInternalCustomerCode
    providerCode
    email
    firstName
    lastName
  }
}

// Variables
{
  selector: {
    merchantInternalCustomerCode: 'customer-123',
  },
  merchantTransactionProviderId: 'provider-id',
}

---

Create a customer with a provider

Creates the customer record in AccruPay and registers it with the connected payment provider.

mutation MerchantApiCustomerCreate(
  $data: MerchantCustomerCreateSchema!
  $merchantTransactionProviderId: String
) {
  merchantApiCustomerCreate(
    data: $data
    merchantTransactionProviderId: $merchantTransactionProviderId
  ) {
    id
    merchantInternalCustomerCode
    providerCode
    providerStatus
  }
}

// Variables
{
  data: {
    merchantInternalCustomerCode: 'customer-123',
    email: 'user@example.com',
    firstName: 'Jane',
    lastName: 'Doe',
    phone: '+15550001234',
    addressLine1: '123 Main St',
    addressCity: 'Austin',
    addressState: 'TX',
    addressPostalCode: '78701',
    addressCountry: 'US',
  },
  merchantTransactionProviderId: 'provider-id',
}

---

Customer fields

Returned by GraphQL operations as MerchantCustomerBaseFragment.

Field	Type	Description
id	string	AccruPay customer ID.
merchantInternalCustomerCode	string | null	Your stable customer identifier.
email	string | null	Customer email address.
firstName	string | null	First name.
lastName	string | null	Last name.
phone	string | null	Phone number.
addressLine1	string | null	Street address line 1.
addressLine2	string | null	Street address line 2.
addressCity	string | null	City.
addressState	string | null	State or province.
addressPostalCode	string | null	Postal / ZIP code.
addressCountry	string | null	ISO 3166-1 alpha-2 country code.
providerCode	string	Provider's customer identifier.
providerError	string | null	Last provider error, if any.
providerLastSyncedAt	string | null	ISO timestamp of last sync.
providerLastVerifiedAt	string	ISO timestamp of last verification.
providerStatus	CUSTOMER_STATUS	Customer status enum: ENABLED, DISABLED, ERROR, UNKNOWN.
transactionProviderId	string	Associated transaction provider.
createdAt	string	ISO creation timestamp.
updatedAt	string	ISO last-update timestamp.

Related

• GraphQL API reference — full mutation and query definitions
• Payment Plans — plans reference customers via merchantInternalCustomerCode
• Payment Methods — stored methods are scoped to a customer