API reference

Customers

A customer is a payer the merchant keeps a record of. Orrerie never checks a payer's identity; this record is whatever the merchant or the payer typed. refund_addresses are addresses the payer gave for refunds. credit_balance is overpayment kept as credit.

The `customer` object

JSON

{
  "id": "cus_8ea07c40qsvv19f7rgmeb8ha",
  "object": "customer",
  "livemode": true,
  "created": "2026-10-01T08:00:00.000Z",
  "updated": "2026-10-01T08:00:00.000Z",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "description": "Wholesale buyer",
  "billing_address": {
    "line1": "12 Market Street",
    "line2": null,
    "city": "Portland",
    "region": "OR",
    "postal_code": "97201",
    "country": "US"
  },
  "refund_addresses": [
    {
      "asset": "ethereum:usdc",
      "address": "0xdbF03B407c01E7cD3CBea99509d93f8DDDC8C6FB",
      "added": "2026-10-01T08:00:00.000Z"
    }
  ],
  "credit_balance": {
    "amount": "0.00",
    "currency": "USD"
  },
  "locale": "en",
  "metadata": {
    "crm_id": "88213"
  }
}

Every field

Fields of the `customer` object

Fields of the customer object
Field	Type	Meaning
`id`	string	Unique identifier: the object prefix, an underscore, 24 lower-case Crockford base32 characters.
`object`	string	The type of this object.
`livemode`	boolean	`true` for live mode (real money); `false` for test mode (simulated payments).
`created`	string (date-time)	When the object was created. RFC 3339, UTC, milliseconds.
`updated`	string (date-time)	When the object last changed.
`name`	string or null	The customer's name, as the merchant or the payer gave it; `null` when none was given.
`email`	string or null	The customer's email address; `null` when none was given. Receipts and invoices go there.
`description`	string or null	The merchant's own note about the customer; `null` for none.
`billing_address`	object or null	The customer's billing address, shown on invoices; `null` when none was given.
`billing_address.line1`	string	The first line of the street address.
`billing_address.line2`	string or null	The second line of the street address; `null` for none.
`billing_address.city`	string	The city or town.
`billing_address.region`	string	The state, province or region.
`billing_address.postal_code`	string	The postal code.
`billing_address.country`	string	The country, an ISO 3166-1 alpha-2 code.
`refund_addresses`	array of objects	Addresses the payer gave for refunds, newest first.
`refund_addresses[].asset`	string	The asset the address takes, as an asset id.
`refund_addresses[].address`	string	The address itself.
`refund_addresses[].added`	string (date-time)	When the payer gave it.
`credit_balance`	object	Overpayment kept as credit for this customer, usable on later invoices.
`credit_balance.amount`	string	The credit, a decimal string.
`credit_balance.currency`	string	The currency of the credit.
`locale`	string	The language of the customer's emails and pages: `auto` or `en`.
`metadata`	object	Up to 50 keys of your own data. Key up to 40 characters, value a string up to 500 characters. Never used by Orrerie; never put secrets or personal data here.

Endpoints

Events

Webhook events whose data.object is an object of this page.