{
  "base": "entity",
  "key": "customer",
  "name": "Customer",
  "pluralName": "Customers",
  "description": "A person or organization with a potential, current or former customer relationship with the business.",
  "version": "0.1.0",
  "properties": [
    {
      "key": "party_type",
      "name": "Party type",
      "description": "Whether the customer is an individual or an organization.",
      "type": "enum",
      "required": true,
      "options": {
        "individual": "Individual",
        "organization": "Organization"
      }
    },
    {
      "key": "lifecycle_stage",
      "name": "Lifecycle stage",
      "description": "The overall commercial relationship, independent of account status. A prospect is a qualified lead; a former customer previously had an established customer relationship.",
      "type": "enum",
      "required": true,
      "options": {
        "customer": "Customer",
        "disqualified": "Disqualified",
        "former_customer": "Former customer",
        "lead": "Lead",
        "prospect": "Prospect"
      }
    },
    {
      "key": "lead_temperature",
      "name": "Lead temperature",
      "description": "Current interest or engagement, independent of qualification. Omit when unknown or not applicable.",
      "type": "enum",
      "options": {
        "cold": "Cold",
        "hot": "Hot",
        "warm": "Warm"
      }
    },
    {
      "key": "qualification_stage",
      "name": "Qualification stage",
      "description": "The qualification reached by a lead or prospect. Omit when unknown or not applicable.",
      "type": "enum",
      "options": {
        "marketing_qualified": "Marketing qualified",
        "sales_qualified": "Sales qualified",
        "unqualified": "Unqualified"
      }
    },
    {
      "key": "status",
      "name": "Account status",
      "description": "The operational account state, independent of lifecycle, billing and payment state. Set explicitly when creating an account.",
      "type": "enum",
      "required": true,
      "options": {
        "active": "Active",
        "closed": "Closed",
        "inactive": "Inactive",
        "pending": "Pending",
        "suspended": "Suspended"
      }
    },
    {
      "key": "commercial_model",
      "name": "Commercial model",
      "description": "How the account is offered. Free means no payment is expected; freemium offers a free tier with paid upgrades. None means no commercial offering applies.",
      "type": "enum",
      "options": {
        "free": "Free",
        "freemium": "Freemium",
        "none": "None",
        "paid": "Paid"
      }
    },
    {
      "key": "billing_stage",
      "name": "Billing stage",
      "description": "The 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.",
      "type": "enum",
      "options": {
        "cancelled": "Cancelled",
        "none": "None",
        "paying": "Paying",
        "trial": "Trial"
      }
    },
    {
      "key": "payment_status",
      "name": "Payment status",
      "description": "Whether 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.",
      "type": "enum",
      "options": {
        "current": "Current",
        "delinquent": "Delinquent",
        "none": "None",
        "past_due": "Past due"
      }
    },
    {
      "key": "is_test_account",
      "name": "Test account",
      "description": "True for an account used for testing rather than a real customer relationship.",
      "type": "boolean"
    },
    {
      "key": "display_name",
      "name": "Name",
      "description": "The name shown for this customer.",
      "type": "string",
      "required": true,
      "pii": true
    },
    {
      "key": "primary_contact",
      "name": "Primary contact",
      "description": "The main person to contact: the customer themselves for an individual, or their representative for an organization.",
      "type": "value",
      "value": "person",
      "pii": true
    },
    {
      "key": "organization",
      "name": "Organization",
      "description": "The organization, when the customer is one.",
      "type": "value",
      "value": "organization"
    },
    {
      "key": "email",
      "name": "Email",
      "type": "string",
      "format": "email",
      "pii": true,
      "compare": "case-insensitive",
      "matchKey": true,
      "sameAs": "https://schema.org/email"
    },
    {
      "key": "phone",
      "name": "Phone",
      "type": "string",
      "format": "phone",
      "pii": true,
      "secure": true,
      "sameAs": "https://schema.org/telephone"
    },
    {
      "key": "addresses",
      "name": "Addresses",
      "description": "Keyed by role, such as billing or shipping.",
      "type": "value",
      "value": "address",
      "pii": true,
      "many": true
    },
    {
      "key": "country",
      "name": "Country",
      "type": "string",
      "format": "country",
      "compare": "case-insensitive"
    },
    {
      "key": "timezone",
      "name": "Timezone",
      "description": "IANA timezone identifier, such as Europe/London.",
      "type": "string"
    },
    {
      "key": "language",
      "name": "Language",
      "type": "string",
      "format": "language",
      "compare": "case-insensitive"
    },
    {
      "key": "currency",
      "name": "Currency",
      "type": "string",
      "format": "currency",
      "compare": "case-insensitive"
    }
  ],
  "actions": [
    {
      "key": "create",
      "name": "Create customer",
      "emits": [
        "created"
      ]
    },
    {
      "key": "update",
      "name": "Update customer",
      "description": "Change customer details. Use change_status or change_lifecycle for account status and lifecycle changes.",
      "emits": [
        "updated"
      ]
    },
    {
      "key": "change_status",
      "name": "Status change",
      "description": "Change account status without changing the lifecycle stage.",
      "emits": [
        "status_changed"
      ]
    },
    {
      "key": "change_lifecycle",
      "name": "Lifecycle change",
      "description": "Change lifecycle stage without changing account status.",
      "emits": [
        "lifecycle_changed"
      ]
    }
  ],
  "events": [
    {
      "key": "created",
      "name": "Customer created"
    },
    {
      "key": "updated",
      "name": "Customer updated"
    },
    {
      "key": "status_changed",
      "name": "Status changed",
      "description": "The account status changed."
    },
    {
      "key": "lifecycle_changed",
      "name": "Lifecycle changed",
      "description": "The commercial relationship moved to another lifecycle stage."
    }
  ]
}