The customer object contains information about your customers. Whenever an end-user pays for one of your products through a payment method, Sphere will auto-create a customer object for that user.

Some use cases for the customer object could be in keeping track of payments that belong to the same customer, seeing whether customers are delinquent on invoices, or facilitating recurring payments.

The customer object

Let's take a look at a full customer object.

{
  "id": "customer_989afe605e144088b141c72b4feda310",
  "amountUSD": 42,
  "created": "2021-01-01T00:00:00.000Z",
  "delinquent": false,
  "personalInfo": {
    "id": "personalInfo_173a8442057946a086bc75b05c84f409",
    "email": "[email protected]",
    "firstName": "John",
    "lastName": "Smith",
    "phoneNumber": "+242-152-1512",
    "address": {
      "id": "address_5462ba8fea4441179464cb5ad921f4e6",
      "line1": "1 Hacker Way",
      "line2": "Building 32 Suite D",
      "city": "Menlo Park",
      "postalCode": "94025",
      "state": "San Francisco",
      "country": "US",
      "updated": "2021-01-01T00:00:00.000Z",
      "created": "2021-01-01T00:00:00.000Z"
    },
    "discord": "JohnSmith#1234",
    "twitter": "@JohnSmith",
    "telegram": "@JohnSmith"
  },
  "updated": "2021-01-01T00:00:00.000Z",
  "wallets": {
    "solana": [
      "GZNnph4EvmyjjL5uzF9xNNTHyV46RzbkW4w4HYU8BQCW",
      "2oHUYyW2PU9VJh4XBs5TbGgzdernunvGqyKth3kxW4ns",
      "DUND26mEDfFeaPsVof3YvbXDRvpuQX7HMUJrLgEWzYw4"
    ],
    "ethereum": [
      "0x95222290DD7278Aa3Ddd389Cc1E1d165CC4BAfe5",
      "0x6d2e03b7EfFEae98BD302A9F836D0d6Ab0002766",
      "0xA4aFFD1175eC7D366503236E8E1273e39f507777"
    ]
  }
}

id: string Unique identifier for the object. Auto-generated by Sphere upon creation.

amountUSD: number Identifies the total amount in USD the customer has spent on your platform.

Purchases via non-stablecoin cryptocurrencies are pegged to the USD value at the time of purchase.

created: string datetime for when the customer was created.

delinquent: boolean Denotes whether a customer is past due on a payment.

personalInfo: object Elements contain personal information about a specific customer.

This information is usually gathered during a payment, if particular elements are marked as required within the features field of a payment method (e.g., payment link or invoice).
Alternatively, you can pass in this information manually when creating a customer.

updated: string datetime for when the customer was last updated.

wallets: object Describes the wallet addresses associated with a customer on different chains.

A customer may have more than one wallet associated, with reconciliation occurring through email address.