Skip to main content
Retrieves detailed information about a specific customer using their unique reference ID.

​
Query

query GetCustomerByRefId($input: GetCustomerByRefIdInput!) {
  getCustomerByRefId(input: $input) {
    customerId
    name
    email
    billingId
    billingCurrency
    hasActiveSubscription
    hasPaymentMethod
    additionalMetaData
    createdAt
    updatedAt
    subscriptions {
      subscriptionId
      status
      plan {
        refId
        displayName
      }
    }
    eligibleForTrial {
      eligible
      productRefId
    }
    promotionalEntitlements {
      id
      status
      feature {
        refId
      }
    }
  }
}

​
Parameters

​
input
GetCustomerByRefIdInput
required
Input object containing the customer identifier

​
Return Type

Returns a Customer object with the following key fields:
FieldTypeDescription
customerIdStringUnique customer identifier
nameStringCustomer display name
emailStringContact email address
billingIdStringID in billing provider (e.g., Stripe)
billingCurrencyCurrencyDefault billing currency
hasActiveSubscriptionBooleanWhether customer has an active subscription
hasPaymentMethodBooleanWhether a payment method is attached
subscriptions[CustomerSubscription]List of customer subscriptions
promotionalEntitlements[PromotionalEntitlement]Granted promotional entitlements
eligibleForTrial[EligibleForTrial]Trial eligibility per product
additionalMetaDataJSONCustom metadata

​
Common Use Cases

Verify the customer’s subscription status when they log in to determine their access level.
Fetch customer details for account settings pages.
Check eligibleForTrial and current subscription to show relevant upgrade options.

​
Error Handling

Error CodeDescription
CUSTOMER_NOT_FOUNDNo customer exists with the provided ID
UNAUTHENTICATEDInvalid or missing API key