Invoicing and Payment Schedules

Socotra supports the following payment schedules:

  • total

  • monthly

  • annually

  • semiannually

  • quarterly

  • every_two_weeks

  • every_week

Billing periods

Billing periods start on the start date of the policy, and stay on the same date of each month (except for the week-based schedules). Invoices become due at the start of the billing period.

The first invoice is issued immediately, and subsequent invoices are issued before the due date according the configured payment terms. Endorsements, cancellations, and withdrawal trigger also immediate invoice issuance.

Invoices

Installments have equal amounts where possible, except for partial periods at the end of the term. Charges are split equally among billing periods, with straight-line, to-the-millisecond proration for partial periods. See also Premium allocation documentation.

Rounding errors are collected on the last invoice for a period of coverage. If the policy duration is not a whole number of months (for example, a policy that runs 2020-01-01 to 2020-06-17), the last billing period will be for less coverage and therefore be for less than the other invoices.

Fees are split evenly across invoices the same manner as premiums.

Payments

A payment object marks an invoice as paid and stores data about the payment. Data fields may be configured on payments, except the Group and Lookup field types.

Note

Socotra does not support partial payment or cash allocation.

Configuration

Payment schedules and terms are defined in policy/policy.json. The contents of invoices are generated automatically. The data to be stored on payments is defined in /payment/payment.json.

Policy Configuration

Add defaultPaymentTerms and paymentSchedules to policy.json, as follows.

  • Both paymentSchedules and defaultPaymentTerms must be in the configuration.

  • Each configured payment schedule option will be available in a dropdown when creating a policy in the Socotra UI.

  • The first payment schedule in the list will be the default.

  • defaultPaymentTerms determines how long before the due date the system will issue the invoice.

{
  "fields": [ ],
  "documents": [ ],
  "defaultPaymentTerms": {
    "amount": 7,
    "unit": "day"
  },
  "paymentSchedules": [
    {
      "type": "total",
      "name": "upfront",
      "displayName": "Up Front"
    },
    {
      "type": "monthly",
      "name": "monthly",
      "displayName": "Monthly"
    },
    ,
    {
      "type": "every_two_weeks",
      "name": "every_two_weeks",
      "displayName": "Biweekly"
    }
  ]
}

Payment Configuration

The file payment.json contains payment configuration. The only configuration for payments is what fields should be saved on them. For the available data types, see Fields. The Group and Lookup field types are not available on payments.

{
  "fields": [
    {
      "name": "payment_ref",
      "title": "Payment reference number",
      "type": "string"
    }
  ]
}

Invoice Templates

When Socotra issues an invoice, it renders the document template policy/invoice.template.liquid. This template has access to the same data available to other Document Templates, as well as data.invoice_financials:

data.invoice_financials: {
    "total_due": BigDecimal,
    "total_due_currency": String
    "gross_premium": BigDecimal,
    "gross_premium_currency": String,
    "gross_taxes": BigDecimal,
    "gross_taxes_currency": String
    "gross_fees": BigDecimal,
    "gross_fees_currency": String,
    "fees": [
        {
            "name": String,
            "display_name": String,
            "amount": BigDecimal,
            "amount_currency": String,
            "description": String
        }
    ],
    "tax_groups": [
        {
            "name": String,
            "display_name": String,
            "amount": BigDecimal,
            "amount_currency": String
        }
    ],
    "financial_transactions": [
        {
            "amount": BigDecimal,
            "amount_currency": String,
            "posted_timestamp": long,
            "policy_modification_locator": String,
            "policy_modification_name": String,
            "type": "premium" | "tax" | "fee",
            "peril_locator": String,
            "peril_name": String,
            "peril_display_name": String,
            "tax_locator": String,
            "tax_name": String,
            "tax_display_name": String,
            "fee_locator": String,
            "fee_name": String,
            "fee_display_name": String
        }
    ]
}

Payment Schedules in the API

When calling the Create Policy endpoint, include the paymentScheduleName in the PolicyCreateRequest4. If not included, the payment schedule will use the default, as described above.