Customer

A person or organization with a potential, current or former customer relationship with the business.

Kind: Entity
Base type: entity
Version: 0.1.0
Definition: customer.json

Properties

Key	Meaning	Type	Notes	Equivalent
`id`	IDOpaque, case-sensitive identifier in the system holding this record.	Text	Required
`external_references`	External referencesReferences keyed by vendor/type. Each key holds a list of IDs with optional routing keys identifying accounts or brands within that namespace.	External reference	Several, keyed by a labelList of values
`party_type`	Party typeWhether the customer is an individual or an organization.	One of: individual, organization	Required
`lifecycle_stage`	Lifecycle stageThe overall commercial relationship, independent of account status. A prospect is a qualified lead; a former customer previously had an established customer relationship.	One of: customer, disqualified, former_customer, lead, prospect	Required
`lead_temperature`	Lead temperatureCurrent interest or engagement, independent of qualification. Omit when unknown or not applicable.	One of: cold, hot, warm
`qualification_stage`	Qualification stageThe qualification reached by a lead or prospect. Omit when unknown or not applicable.	One of: marketing_qualified, sales_qualified, unqualified
`status`	Account statusThe operational account state, independent of lifecycle, billing and payment state. Set explicitly when creating an account.	One of: active, closed, inactive, pending, suspended	Required
`commercial_model`	Commercial modelHow the account is offered. Free means no payment is expected; freemium offers a free tier with paid upgrades. None means no commercial offering applies.	One of: free, freemium, none, paid
`billing_stage`	Billing stageThe account billing relationship. Cancellation does not itself end access or close the account. For multiple subscriptions this is an account summary; individual subscription states remain separate.	One of: cancelled, none, paying, trial
`payment_status`	Payment statusWhether account payment obligations are met. None means no obligation applies; current means obligations are met; past due means a payment is overdue; delinquent means it meets the business's escalation policy. This is an account summary when several subscriptions exist.	One of: current, delinquent, none, past_due
`is_test_account`	Test accountTrue for an account used for testing rather than a real customer relationship.	True or false
`display_name`	NameThe name shown for this customer.	Text	RequiredPersonal data
`primary_contact`	Primary contactThe main person to contact: the customer themselves for an individual, or their representative for an organization.	Person	Personal data
`organization`	OrganizationThe organization, when the customer is one.	Organization
`email`	Email	Email address	Match keyCompared ignoring casePersonal data	https://schema.org/email
`phone`	Phone	Phone number (E.164)	Personal data, masked	https://schema.org/telephone
`addresses`	AddressesKeyed by role, such as billing or shipping.	Address	Several, keyed by a labelPersonal data
`country`	Country	Country code (ISO 3166-1 alpha-2)	Compared ignoring case
`timezone`	TimezoneIANA timezone identifier, such as Europe/London.	Text
`language`	Language	Language tag (BCP 47)	Compared ignoring case
`currency`	Currency	Currency code (ISO 4217)	Compared ignoring case

Actions

`create`	Create customer	Raises `created`
`update`	Update customerChange customer details. Use change_status or change_lifecycle for account status and lifecycle changes.	Raises `updated`
`change_status`	Status changeChange account status without changing the lifecycle stage.	Raises `status_changed`
`change_lifecycle`	Lifecycle changeChange lifecycle stage without changing account status.	Raises `lifecycle_changed`

Events

`created`	Customer created
`updated`	Customer updated
`status_changed`	Status changed
`lifecycle_changed`	Lifecycle changed

Example

{
  "id": "customer_123",
  "external_references": {
    "stripe/customer": [
      {
        "routing_key": "brand_1",
        "id": "cust_32HDDsd"
      },
      {
        "routing_key": "brand_2",
        "id": "cust_87ABCxy"
      }
    ],
    "fortifi/customer": [
      {
        "id": "CST_456"
      }
    ]
  },
  "party_type": "individual",
  "display_name": "Alex Morgan",
  "primary_contact": {
    "given_name": "Alex",
    "family_name": "Morgan"
  },
  "email": "alex.morgan@example.com",
  "phone": "+447700900123",
  "addresses": {
    "billing": {
      "line1": "1 High Street",
      "city": "London",
      "postal_code": "SW1A 1AA",
      "country": "GB"
    }
  },
  "country": "GB",
  "language": "en-GB",
  "currency": "GBP",
  "lifecycle_stage": "customer",
  "status": "active",
  "timezone": "Europe/London",
  "is_test_account": false,
  "commercial_model": "paid",
  "billing_stage": "trial",
  "payment_status": "none"
}