SOsolvapay
Customers

Get customer by reference, externalRef, or email

Changed on

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.

get/v1/sdk/customers

Request

Query parameters

referencestring
Example:cus_3c4d5e6f7g8h

Customer reference identifier (use exactly one query parameter)

externalRefstring
Example:auth_user_12345

External reference ID from your auth system (use exactly one query parameter)

emailstring
Example:customer@example.com

Customer email address (use exactly one query parameter)

Response

Customer retrieved successfully

emailstring required

Customer email address

externalRefstring

External reference ID from your auth system (if set during creation or update)

namestring required

Customer full name

referencestring required

Customer reference identifier

Example response

{
  "email": "customer@example.com",
  "externalRef": "auth_user_12345",
  "name": "John Doe",
  "purchases": [
    {
      "amount": 9900,
      "cancellationReason": "Customer request",
      "cancelledAt": "2025-10-28T10:00:00Z",
      "currency": "GBP",
      "customerEmail": "customer@example.com",
      "customerRef": "cus_3C4D5E6F",
      "endDate": "2025-11-27T10:00:00Z",
      "exchangeRate": 1.32,
      "isRecurring": true,
      "origin": "paid",
      "originalAmount": 7500,
      "planRef": "pln_abc123",
      "planSnapshot": {
        "currency": "USD",
        "isMetered": true,
        "name": "Pro Monthly",
        "price": 2999,
        "reference": "pln_1A2B3C4D"
      },
      "productName": "API Gateway Manager",
      "productRef": "prd_abc123",
      "reference": "pur_1A2B3C4D",
      "startDate": "2025-10-27T10:00:00Z",
      "status": "active",
      "usage": {
        "periodEnd": "2025-11-01T00:00:00Z",
        "periodStart": "2025-10-01T00:00:00Z"
      }
    }
  ],
  "reference": "cus_3c4d5e6f7g8h"
}

Changes

  • e13ee57d07a6Revision changes
    • info

      added to the // response property allOf list for the response status

    • info

      removed from the // response property allOf list for the response status

  • aacdf8ae7816Revision changes
    • breaking

      the response property // became optional for the status

    • breaking

      the // response's property type changed from object to no type for status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added to the // response property allOf list for the response status

    • info

      added the required property // to the response with the status

    • info

      added the required property // to the response with the status

    • info

      added the required property // to the response with the status