Event Payload Reference

Complete field-by-field reference for the events PolicyOne publishes to events:policy. BillingOne's PolicyEventsConsumer receives these as the data field of each Redis Stream entry.

← Event Flow  |  Operations →

Envelope — PolicyEvent<T>

Every event, regardless of type, is wrapped in this envelope. Defined in packages/events/src/envelope.ts.

type PolicyEvent<T> = {
  id:               string   // UUID — matches event_outbox.id. Use for idempotency.
  type:             string   // 'policy.bound' | 'policy.issued' | ...
  version:          number   // Schema version. Increment when payload shape changes.
  tenantId:         string   // UUID — org / tenant that owns this policy.
  policyId:         string   // UUID — policy.policies.id
  sequenceNumber:   number   // Monotonic per-policy sequence. Guarantees ordered delivery.
  requiresOrdering: boolean  // If true, consumer must process in sequenceNumber order.
  occurredAt:       string   // ISO-8601 UTC timestamp of the originating DB transaction.
  payload:          T        // The domain-specific payload (see below).
}

Redis message format:

XADD events:policy * data '{"id":"...","type":"policy.bound","version":1,...}'

A single data field containing the full JSON-serialised envelope.

policy.bound — PolicyBoundPayload

When: Inside bindQuoteToPolicy() — the same transaction that inserts policy.policies.

BillingOne action: Create billing account, configure payment plan, stage first invoice.

Source: packages/events/src/policy-events.ts

type PolicyBoundPayload = {
  type:             'policy.bound'
  policyNumber:     string           // e.g. "POL-2026-000042"
  customerId:       string           // PartyOne customer reference (UUID)
  producerCode:     string | null    // e.g. "AGT-00123"
  agencyId:         string | null    // UUID of the producing agency
  stateCode:        string | null    // e.g. "CA", "TX"
  inceptionDate:    string           // YYYY-MM-DD — policy start date
  expirationDate:   string           // YYYY-MM-DD — policy end date
  lobCode:          string           // e.g. "Commercial_Property", "PersonalAuto"
  productRef:       string | null    // e.g. "CCP", "PA"
  sourceQuoteId:    string           // UUID — the quote that was bound
  submissionId:     string           // UUID — the parent submission
  writtenPremiumCents: number | null // Base premium in cents (before tax/surcharge/fee)

  // ── Billing fields (from policy.quote_billing) ──────────────────────────
  billing: {
    paymentPlanCode: string          // e.g. "pif" | "quarterly" | "monthly-12"
    billingMethod:   string          // "direct_bill" | "agency_bill" | "mortgage_bill"
    discountCodes:   Array<{
      code:   string
      pct:    number | null          // Percentage discount, e.g. 5 = 5%
      amount: number | null          // Fixed dollar discount
      reason: string | null
    }>
  }

  // ── Premium breakdown (from quotes.rating_response) ─────────────────────
  premium: {
    subtotalPremium: number          // Base premium (quotes.rating_response.subtotal_premium)
    taxes:           number          // Sum of charges where category='tax'
    surcharges:      number          // Sum of charges where category='surcharge'
    fees:            number          // Sum of charges where category='fee'
    totalDue:        number          // quotes.rating_response.total_due
    totalPremium:    number          // == totalDue. Forwarded to BillingOne as totalPremium.
    chargeItems: Array<{
      code:     string               // e.g. "CA-SURPLUS-LINES"
      label:    string | null
      category: 'tax' | 'surcharge' | 'fee'
      amount:   number
    }>
  }
}

Full Example

{
  "id": "018f4c2e-6a1d-7000-8f5b-3c9d2a1b4e8f",
  "type": "policy.bound",
  "version": 1,
  "tenantId": "018e1234-0000-7000-aaaa-000000000001",
  "policyId": "018f4c2e-0000-7000-bbbb-111111111111",
  "sequenceNumber": 1,
  "requiresOrdering": true,
  "occurredAt": "2026-06-02T14:32:10.000Z",
  "payload": {
    "type": "policy.bound",
    "policyNumber": "POL-2026-000042",
    "customerId": "018e5678-0000-7000-cccc-222222222222",
    "producerCode": "AGT-00123",
    "agencyId": "018e9abc-0000-7000-dddd-333333333333",
    "stateCode": "CA",
    "inceptionDate": "2026-07-01",
    "expirationDate": "2027-07-01",
    "lobCode": "Commercial_Property",
    "productRef": "CCP",
    "sourceQuoteId": "018f1111-0000-7000-eeee-444444444444",
    "submissionId": "018f2222-0000-7000-ffff-555555555555",
    "writtenPremiumCents": 1000000,
    "billing": {
      "paymentPlanCode": "quarterly",
      "billingMethod": "direct_bill",
      "discountCodes": []
    },
    "premium": {
      "subtotalPremium": 10000.00,
      "taxes": 450.00,
      "surcharges": 200.00,
      "fees": 50.00,
      "totalDue": 10700.00,
      "totalPremium": 10700.00,
      "chargeItems": [
        { "code": "CA-SURPLUS-LINES", "label": "CA Surplus Lines Tax", "category": "tax", "amount": 450.00 },
        { "code": "CA-EARTHQUAKE-SURCHARGE", "label": "Earthquake Surcharge", "category": "surcharge", "amount": 200.00 },
        { "code": "POLICY-FEE", "label": "Policy Fee", "category": "fee", "amount": 50.00 }
      ]
    }
  }
}

policy.issued — PolicyIssuedPayload

When: Inside issuePolicyRecord() transaction (after UW approval).

BillingOne action: Activate the payment schedule, send the first invoice to the insured.

type PolicyIssuedPayload = {
  type:           'policy.issued'
  policyNumber:   string         // e.g. "POL-2026-000042"
  customerId:     string         // PartyOne customer reference (UUID)
  inceptionDate:  string         // YYYY-MM-DD
  expirationDate: string         // YYYY-MM-DD
  sourceQuoteId:  string | null  // UUID of the originating quote
  submissionId:   string | null  // UUID of the originating submission
}

policy.cancelled — PolicyCancelledPayload

When: (Planned) — when a policy is cancelled mid-term.

BillingOne action: Stop future charges, calculate unearned premium refund.

type PolicyCancelledPayload = {
  type:                 'policy.cancelled'
  policyNumber:         string
  customerId:           string
  cancellationDate:     string         // YYYY-MM-DD
  cancellationReason:   string | null
  unearnedPremiumCents: number | null  // Amount to be refunded
}

policy.renewed — PolicyRenewedPayload

When: (Planned) — when a renewal quote is bound.

BillingOne action: Create new billing period, carry forward billing method.

type PolicyRenewedPayload = {
  type:                'policy.renewed'
  policyNumber:        string
  priorPolicyId:       string   // UUID of the expiring policy
  newInceptionDate:    string   // YYYY-MM-DD
  newExpirationDate:   string   // YYYY-MM-DD
  renewalPremiumCents: number | null
}

Source of Truth Files