Invoicing and Payment Schedules



The scheduling of invoices is controlled by the Payment Schedule Plugin. See Legacy Invoice Scheduling below for details on how Socotra works if the payment schedule plugin is not implemented.

The payment schedule name is set on new policies on creation, either in the UI or when calling the Create Policy endpoint by including the paymentScheduleName in the PolicyCreateRequest. If not included, the payment schedule will use the default, as described below.

The payment schedule name (along with other data) is provided to the payment schedule plugin which then determines how to interpret and implement the schedule.

Manual Schedule Changes

Along with the ability to control the behavior of a payment schedule, the payment schedule plugin can change an existing policy’s payment schedule from one schedule to another. This affects only future invoices; already-generated invoices will not be affected. To change a policy’s payment schedule, use the following endpoint:

Change Payment Schedule
POST /policy/{policyLocator}/paymentSchedule
    Response: void
newPaymentScheduleName string


The new payment schedule will be persisted on the policy, and future transactions will be invoiced with the new schedule.


Manually changing the payment schedule requires use of the payment schedule plugin.

Payment Schedule Changes with Endorsements and Renewals

Sometimes policy pricing is dependent on the policy’s payment schedule. For example, you may charge a slightly higher premium for monthly schedules vs. those that are paid up front. For these cases, a payment schedule change must be accompanied by an endorsement in order to trigger the price change.

The payment schedule change operation can be combined with the endorsement or renewal operation to prevent scheduling invoices twice, which could cause problems if any invoices in the first set are issued before they can be rescheduled.

Set the newPaymentScheduleName property on the endorsement or renewal to have the schedule change take place within the policy transaction.

When the Endorsement or Renewal becomes accepted, the new payment schedule is used to generate invoices.

When the Endorsement or Renewal becomes issued, the new payment schedule is persisted on the policy itself and used for all invoice scheduling thereafter.


The policy only has one payment schedule at a time. If an out of sequence transaction is executed, there will be no attempt to resolve what the payment schedule was at the time of the first transaction.


Changing payment schedules in conjunction with an endorsement or renewal requires use of the Payment Schedule Plugin. Enable it before using this feature.


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.

Socotra does not support partial payment or cash allocation in the base version of the application. See the Socotra Plugin Reference Implementations for an implementation of the payment schedule plugin that can be configured to handle some of the related use cases.


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": number,
    "total_due_currency": string
    "gross_premium": number,
    "gross_premium_currency": string,
    "gross_taxes": number,
    "gross_taxes_currency": string
    "gross_fees": number,
    "gross_fees_currency": string,
    "fees": [
            "name": string,
            "display_name": string,
            "amount": number,
            "amount_currency": string,
            "description": string
    "tax_groups": [
            "name": string,
            "display_name": string,
            "amount": number,
            "amount_currency": string
    "financial_transactions": [
            "amount": number,
            "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

Invoice Rendering

For policy issuance, the first invoice may be rendered either when the governing quote is accepted or the policy is issued. This is controlled with the generatingEvent property in policy.json. See the Quotes documentation for details.

For endorsements, renewals, cancellations, and reinstatements, invoices are rendered when the associated transaction reaches accepted state.

For premium reports, invoices are rendered when the premium report is issued.

Legacy Invoice Scheduling

Invoices are normally scheduled with the Payment Schedule Plugin. If the plugin is not implemented, Socotra will fall back to legacy behavior as described here.

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.

Invoice Metadata

When examining a list of invoices, such as from the fetch a policy's invoices endpoint, the properties invoiceType and transactionIssued property on the PolicyInvoiceResponse can be used to understand the origin of the invoice.

The invoiceType property can take the following values:

  • newBusiness

  • endorsement

  • renewal

  • cancellation

  • reinstatement

  • installment

  • premiumReporting

  • other

The types newBusiness, endorsement, renewal, cancellation, and reinstatement are the first in the series of installments after the given transaction type. Subsequent installments are given the type installment.

The type premiumReporting is used the invoice attached to each issued premium report.

The type other is used for all other cases. This is currently only for stand-alone invoices for fees, and for invoices generated before the introduction of this feature.

When a transaction is accepted, an invoice for the transaction is generated, and it is given the invoice type based on what type of transaction it is. If the transaction remains unissued, the transactionIssued property for that invoice will be false. After the underlying transaction is issued, the transactionIssued property will be set to true.