After completing this lesson, you will be able to:

  • Define a Payout
  • Set the Current Period
  • Create a manual Adjustment
  • Create a Bonus

Payout Processes

The payout process is a task that you will run once you have completed the posting of all transaction files for a period. When you run the Payout process, vouchers and statements for a specific period will be generated.

Setting the Current Period

When we are calculating commissions and payouts, it’s important to make sure all transactions in the current date range, or period, are grouped together. This allows the system to create a single payout for each payee, and to group transactions appropriately for reporting and other management purposes. The period in APMe is defined by the Process Year (PerYear) and Process Month (PerMonth) of the Period table. Transaction processing is also connected to the Period record. Until the process is finalized, the next period cannot commence.

While most of the time the period represents a month, it can also represent a semi-monthly or weekly time frame.

Procedure: To set the current period:

  1. From the Integration portal, select Configuration - Current Period.
  2. Enter the month and year for the period you wish to set.
  3. Select Set Current.


Before we go into the details of payouts, it helps to know about Retroactivity. Retroactivity refers to any changes that need to be made to past transactions, causing the payout to be re-evaluated and re-calculated.

To understand what this means, let’s look at an example. Say that our producers have a Broker Type of either Qualified or Preferred. Our compensation rule pays a 5% commission to qualified producers, and 7% to preferred producers.

Deborah Willis has a Broker Type of Qualified, so her sale of a policy with a US$1500 premium paid a commission of US$75 in January. However, a month later her management determined that her broker type should have been Preferred starting at the beginning of January. Since Deborah was already compensated for the premium, how can we ensure that she is paid the difference for a period that is already passed?

That’s where Retroactivity comes in. Retroactivity allows you to configure the system to automatically reprocess any transactions that were based on the Broker Type (or any other data). This is done by configuring Retroactivity Rules.

To see the retroactivity rule that applies for the Broker Type, from the Administrator portal, select Commission Settings – Retroactivity Search and open the item labelled Broker Detail Change.

In this view, we can see that the IsInsert and IsDelete columns are set to No, and the IsUpdate column is set to Yes. This means the commission will only be recalculated if the broker detail is modified, but not if a broker detail is created or deleted.

The Key Fields column lists the fields that would trigger a retroactive update. You can see that one of the listed fields is Broker Type, so we don’t need to make any changes.

The Expression Qualifier field can be used to define the rule matching criteria in case other criteria need to be met for the retroactivity to take place.

The Retro Periods column defines the number of reprocessing periods (prior to the current period).

The Retro Processing Periods column can contain an expression that calculates the number of retro periods by subtracting a number of months from the current period.

The Expression Retro Mark Filter is used to define additional identification criteria for transaction reprocessing.

If the Approval Required field is checked, changes must be approved before the application will trigger transactions to be reprocessed.

Payout Types

Earlier in this course, we selected a Payout Type when we imported and posted transactions. The Payout Type we select is important when the Payout process runs.

Payout Types allow records for different groups of payees to be processed independently. For example, Agencies may receive payment on a monthly basis while Agents receive payments weekly. Some other ways payout types can be configured include:

  • Whether payouts are allowed
  • Whether a payout type can calculate a bonus
  • Whether a cap on commission is applied
  • Whether certain transactions are held

Payout Types can be managed from the Administrator portal under Commission Settings – Payout Types. The image below shows the basic settings for the CLIENT Payout that we are using in our examples.

Key Payout Tasks

The Payout process consists of a total of 52 tasks. Clearly, you don’t need to know what all of them do, but several key tasks perform the core functionality of the payout. Knowing what these tasks do can help you with auditing and troubleshooting.

Key Task NameDescription
Computation CalculationTransactions are evaluated in their respective formula and computed.
Bonus ProcessingBroker Bonus and Bonus Set are evaluated, the Bonus is computed and a BrokerBonHis record is created.
Retro Mark Config ChangesIf we make a change in the system that has been configured to trigger retroactivity (such as unexpiring a member), this task creates an audit record that is ready to be processed during the next payout.
Repost Transaction TaskThis task is part of the retroactivity feature. It has the job of processing transactions that should be modified based on the retroactivity rules, as if they were new.
Apply HoldsThe Apply Holds task reads Broker History records that aren't evaluated and held, and evaluates them through the list of holds by the sequence number of the Hold.
Generate VoucherGroups Broker History records without a voucher number into a voucher by vendor that can be broken further down by vendor , finentity, and so on, as specified in the voucher option. This task sets the voucher number on the Broker History and the Run List voucher.
Extract StatementReads the voucher and creates the Statement in PDF and statement attachments, and in the statement table.

Exercise: Run the Payout process

In this exercise, we will run the Payout process for transactions in our current period: January 2022.


  1. Run the Payout process.

    1. From the Manager portal, select Processing - Payout.

    2. Select Run.

    3. Select the following in the dialog box:

      • Payout Type ID: CLIENT Payout
      • Process Type: Full
      • Auto Finalize: No
      • Include Retro: Yes
      • Generate Adjustments: Yes
      • System Environment Level Override: Leave Unchecked
      • Repost All: No
      • Statement Start Date: Leave Empty
      • Statement End Date: Leave Empty
      • Statement Message: Leave Empty
      • Log Level: Leave Empty
    4. Select OK.

Manual Adjustments

Manual Adjustments enable the user to enter financial information that is calculated outside of the APMe system. It enables a one-time payment or deduction to a specified Producer. Manual Adjustments can be added and viewed under the Manager portal under Producers – Manual Adjustments.

For example, let’s say that Deborah Willis earned a special commission on a sale of a policy to Keith Branch, but no compensation plan is in place to award the commission amount. You can create a manual adjustment, which would then be processed during Payout.

Adjustment Types

The Adjustment Type field is a required dropdown field for manual adjustments. You can manage a list of adjustment types by adding values to the ADJTYPES code type.

Once you have added your adjustment types, you can add manual adjustments two ways:

  • Enter the details of the adjustment in the user interface.
  • Create a file with a list of adjustments and processing the file via the Integration Portal. When you create a manual adjustment, the following fields are required:

    • Producer ID
    • Vendor ID
    • Bill Month/Year
    • Premium Month/Year
    • Adjustment Type
    • Adjustment Description

    Other optional fields can be used to ensure accurate payouts, including:

    • Customer ID
    • Contract Number
    • Payout Type ID
    • Income Flag

    The image below shows a manual adjustment that pays Deborah Willis the $150 special commission in January 2022, using an adjustment type of Manual Adjustment. Notice that the Producer ID and Vendor ID match. This is quite common, and means that Deborah is both the credentialled producer and the payee for the commission.

Approving an Adjustment

You may also notice that the status of the manual adjustment is set to Open. Manual adjustments must be approved before they can be paid. Approving the adjustment will change the status to Approved. The adjustment will no longer be editable, and the amount will be included in the payout for the process year and month.

Bonuses and One Time Payouts

So far, we have covered using APMe to calculate commissions, but it is also possible to create bonus scenarios. A bonus is a payout that is not generally based on transactions, and is typically driven by a query. Bonuses are calculated after transactions are posted, which makes it possible to use transaction-based calculations as input to a bonus.

Bonuses can be set up to run at specific times, or with specific payouts.

A bonus can have one of two Bonus Types: Performance or Expression. A Performance bonus type calculates based on broker performance, while an Expression Bonus Type allows you to configure the bonus calculation as a Groovy expression. The expression contains a query that pulls aggregated data or other details that can be used as input for the bonus.

Let’s look at a simple example in which we want to pay out a bonus of $1500 to our agents. Our first step is to create an expression called BON-BonusFixed that returns a value of 1500. Also notice the Use Context; setting this field to Bonus allows us to select the expression in a bonus record.

Expressions can be added in the Manager portal under Configuration – Expression Search.

Now, let’s look at the key fields on the bonus record itself. To create a new bonus, from the Manager portal, select Payment Plans – Bonus Search.

  1. Enter a unique Bonus ID and Name. Let's call this one AgentBonus.
  2. Select the Adjustment Type. The choices are Bonus and Manual Adjustment. In this scenario we will choose Bonus.
  3. Select the Bonus Type. In this scenario we will use Expression.
  4. Select the Expression to calculate the bonus amount. We’ve selected the BON-BonusFixed expression we saw earlier.
  5. Set the Payment Type to Per Broker or Query. If you select Per Broker, you can add a rule that indicates whether each broker will get a payment or not (regardless of the amount). If you select query, you can define who gets paid in the driver query. In this scenario, we don’t have anything in our expression that identifies the payee, so we are selecting Per Broker.
  6. The Financial Company and GL Code are optional, but if selected, they can pass through information that can be used by Accounts Payable or Payroll.
  7. Select the Generate Broker History box if a BrokerHistory record should be created with the bonus. Generally, this box should be checked.
  8. Finally, we select the starting period and ending period, and the Payout Type ID. Since this is an annual bonus, we’ve set the Compute Frequency to Annual.

Log in to track your progress & complete quizzes