> ## Documentation Index
> Fetch the complete documentation index at: https://docs.solvapay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get customer by reference, externalRef, or email

> Retrieves a customer's details using their unique reference ID, externalRef, or email. Use query parameter 'reference' to look up by customer reference, 'externalRef' for external auth ID, or 'email' for customer email. Exactly one parameter must be provided. Returns the customer's name, email, and active purchases. Only customers owned by the authenticated provider can be accessed.



## OpenAPI

````yaml /api-reference/openapi.json get /v1/sdk/customers
openapi: 3.0.0
info:
  contact: {}
  description: The SolvaPay REST API specification
  title: SolvaPay REST API
  version: '1.0'
servers: []
security: []
tags: []
paths:
  /v1/sdk/customers:
    get:
      tags:
        - Customers
      summary: Get customer by reference, externalRef, or email
      description: >-
        Retrieves a customer's details using their unique reference ID,
        externalRef, or email. Use query parameter 'reference' to look up by
        customer reference, 'externalRef' for external auth ID, or 'email' for
        customer email. Exactly one parameter must be provided. Returns the
        customer's name, email, and active purchases. Only customers owned by
        the authenticated provider can be accessed.
      operationId: CustomerSdkController_getCustomerByQuery
      parameters:
        - description: Customer reference identifier (use exactly one query parameter)
          in: query
          name: reference
          required: false
          schema:
            example: cus_3c4d5e6f7g8h
            type: string
        - description: >-
            External reference ID from your auth system (use exactly one query
            parameter)
          in: query
          name: externalRef
          required: false
          schema:
            example: auth_user_12345
            type: string
        - description: Customer email address (use exactly one query parameter)
          in: query
          name: email
          required: false
          schema:
            example: customer@example.com
            type: string
      responses:
        '200':
          content:
            application/json:
              example:
                email: customer@example.com
                externalRef: auth_user_12345
                name: John Doe
                purchases:
                  - amount: 9900
                    currency: USD
                    endDate: '2025-11-27T10:00:00Z'
                    productName: API Gateway Manager
                    productRef: prd_abc123
                    reference: pur_1A2B3C4D
                    startDate: '2025-10-27T10:00:00Z'
                    status: active
                reference: cus_3c4d5e6f7g8h
              schema:
                $ref: '#/components/schemas/CustomerResponse'
          description: Customer retrieved successfully
        '400':
          content:
            application/json:
              schema:
                example:
                  error: Bad Request
                  message: Must provide exactly one of reference, externalRef, or email
                  statusCode: 400
          description: >-
            Invalid request - must provide exactly one of reference,
            externalRef, or email
        '404':
          content:
            application/json:
              schema:
                example:
                  error: Not Found
                  message: Customer not found
                  statusCode: 404
          description: Customer not found
      security:
        - SecretKey: []
components:
  schemas:
    CustomerResponse:
      properties:
        email:
          description: Customer email address
          example: customer@example.com
          type: string
        externalRef:
          description: >-
            External reference ID from your auth system (if set during creation
            or update)
          example: auth_user_12345
          type: string
        name:
          description: Customer full name
          example: John Doe
          type: string
        purchases:
          description: Active purchases
          items:
            $ref: '#/components/schemas/PurchaseInfo'
          type: array
        reference:
          description: Customer reference identifier
          example: cus_3c4d5e6f7g8h
          type: string
      required:
        - reference
        - name
        - email
      type: object
    PurchaseInfo:
      properties:
        amount:
          description: Amount in USD cents (normalised for aggregation)
          example: 9900
          type: number
        cancellationReason:
          description: Reason for cancellation
          example: Customer request
          type: string
        cancelledAt:
          description: When purchase was cancelled
          example: '2025-10-28T10:00:00Z'
          type: string
        currency:
          description: ISO 4217 currency code of the customer-facing charge
          example: GBP
          type: string
        endDate:
          description: End date of purchase
          example: '2025-11-27T10:00:00Z'
          type: string
        exchangeRate:
          description: Exchange rate from original currency to USD
          example: 1.32
          type: number
        originalAmount:
          description: Original amount in the payment currency (minor units)
          example: 7500
          type: number
        planRef:
          description: Plan reference from the plan snapshot, for reliable plan matching
          example: pln_abc123
          type: string
        planSnapshot:
          description: Snapshot of the plan at time of purchase
          type: object
        productName:
          description: Product name
          example: API Gateway Manager
          type: string
        productRef:
          description: Product reference
          example: prd_abc123
          type: string
        reference:
          description: Purchase reference
          example: pur_1A2B3C4D
          type: string
        startDate:
          description: Start date
          example: '2025-10-27T10:00:00Z'
          type: string
        status:
          description: Purchase status
          example: active
          type: string
      required:
        - reference
        - productName
        - status
        - startDate
        - amount
        - currency
      type: object
  securitySchemes:
    SecretKey:
      bearerFormat: JWT
      description: >-
        Provider secret API key (sk_live_… / sk_test_…) supplied as a Bearer
        token.
      scheme: bearer
      type: http

````