Payout Records

This article describes the Payout Record entity, which was introduced to help performance situations when too many Rebate Records were used.

The information is intended for Configuration Engineers who are going to implement rebate management for a customer solution.

Business Use Case

The customer needs to calculate rebates/accruals/payouts on a much lower level, e.g.:

Not on customer lever, but maybe down to store/shop level.
Not on product group level, but maybe per SKU, customer and payout period.

Terminology

Accruals – Accrual/s - Refers to a time-procedural process usually carried out by accounting departments to "accrue" money in the bank for payouts that are expected to be made in the future.In other words, it’s a calculation of additional money the company must put aside, to have enough money available to pay the rebate to the customer at the time of payout date.Accruals usually need to be exported to the external system every month.

Payout – How much money to pay to the customer.Frequency of export of Payout information to the external system depends on the payout period.

Payout period – How often is the rebate money paid to the customer.Usually it’s annually, semi-annually, quarterly or monthly.

Payout date – On what date should the money be given to the customer.

Concept

What is a Payout Record

Payout Record:

Is a data-entity
- on which you can store the same data as Rebate Record - rebates, accruals, payouts, etc.
- which is always associated with a Rebate Record, so
  - the Rebate Record can have higher level/summary information,
  - and its Payout Records will contain the calculations on more fine-grained level.
- which is "lightweight" - does not have "rich" features like calculation contexts, workflow, overrides.
Is managed by the Rebate Logic (in Rebate Record context)
- which allows you to quickly create/update/delete even hundreds of thousands of those records.

System Usecase

Number of Records

Generally, you can use Payout Records whenever your solution would lead to the need for generation/calculation of a large amount of Rebate Records.

Because Rebate Records have many "rich" features like calculation contexts, workflow, overrides, etc., their handling is more complex and they are not intended to be used, when your solution needs more than roughly 100 Rebate Records per Rebate Agreement.

So in solutions, where customer requirement would lead to more than 100 Rebate Records (many times they need far more, even hundreds of thousands), do use Payout Records.

2^nd Level of Calculations

You can also consider Payout Records, when it would be handy to have more levels of calculations. (But also bear in mind that only Rebate Record is approvable, if that’s what you need.)

When your solution needs two levels of calculation:

1^st level - Summary calculations (possibly for group of customers, or groups of products).
2^nd level - More fine-grained calculation (on customer ID level, on SKU level, etc).

Comparison of Rebate Record and Payout Record

	Rebate Record	Payout Record

	Rebate Record	Payout Record
Amount per Rebate Agreement	Up to 100	Up to hundreds of thousands
Features	Calculation Contexts, Workflow, Overrides	None (it’s a "Lightweight" data entity)
Handling	Creation by Logic, but update/delete/status by system	All management up to Logic - create/update/delete
"Parent" entity	Rebate Line Item	Rebate Record

Flow of Work with Payout Records

The flow of the Rebate Management is usually as follows:

Design / Create Rebate Strategy (RBA).
Accrue expected payouts as time passes (RR).
Finalize accrual into customer payment (Approve RR & Create PYR).

From the diagram you can see that the Payout Records are created only at the time of calculation (not creation) of Rebate Records.

The colors are in sync with the Data Model diagram, so you can distinguish the stages when the Payout Record is created/updated and when it’s exported out to external system.

Figure 1. Work with Price records during three different stages - during creation of the Agreement, during periodic recalculations of Rebate Records and when the Rebate Record get's approved.

Data Model

Payout Records are associated with the Rebate Records. So the Payout Record is not a "replacement" of the Rebate Record, but rather a solution to store fine-grained information calculated in the context of the Rebate Record.

Figure 2. Relation 1:n between Rebate Agreement, Rebate Line, Rebate Record and Payout Record

You can also review the more detailed ERD diagram below, in which you could notice:

Some fields are found in more entities - for example startDate, endDate and payoutDate - but they can have different values among the entities (i.e., RALI, RR and PYR), if you need to store more fine-grained accruals/rebates for different time periods (e.g., RALI can have validity per year, RR per quarter and PYR per month).
The PYR fields gives you a lot of flexibility in how you will use them. Only a couple of fields are built-in and for the rest you need to use the attributeX columns.

Types of Payout Records

Each Payout Record has a type, which gives it certain meaning - what kind of information it actually stores.

You can think about it in a similar way as RebateRecordSet can be used (for Rebate Records).

A few examples of values used across projects in the Payout Record Type field:

"Summary"
"Detail"
"Accrual Summary"
"Accrual Detail"
"Payout"
etc.

Implementation / Configuration

Logics

You’re working with Payout Records:

Only in Rebate Logic, in "Rebate Record" context.
- This context contains the current Rebate Record via api.currentItem() and this is the Rebate Record, to which the newly added Payout Records will be linked to.
Via object PayoutRecordManager which is available via binding variable payoutRecords.

Code sample - Create Payout Records in the Rebate Logic (Rebate Record context)

def rebateRecord = api.currentItem()

payoutRecords.bulkLoadMode()                    //❶

//payoutRecords.delete()                        //❷

payoutRecords.add(
    "Payout",
    "${rebateRecord.id}-${productId}-${customerId}",
    [
        startDate  : rebateRecord.startDate,    //❸
        endDate    : rebateRecord.endDate,      //❸
        payoutDate : rebateRecord.payoutDate,   //❸

        attribute1: customerId,
        attribute2: productId,
        attribute3: rebateValue,
        attribute4: currency,
        attribute5: rebatePct,
        attribute6: paymentPeriod,
        attribute7: rebateRecord.attribute2
    ]
)

payoutRecords.flush()                           //❹

❶ Use if you’re generating huge amount of Payout Records.
❷ Delete all Payout Records linked to the current Rebate Record.This is important, if you know that it’s possible that you’re going to create a different set of the Payout Records during recalculation of the Rebate Record.
❸ In this sample we are using the same dates as on the Rebate Record, but in some other use-cases you might use more granular date ranges.
❹ When you use bulk mode, the flush() must be called once all records have been added or updated, otherwise the more recent additions and updates will not be persisted in the database.If you do not use the bulk mode, the logic will flush the data at the end anyway, so it’s not necessary to call it explicitly.

During testing of the logic, the functions on payoutRecords do not do anything, so no records will be stored into database and ultimately if you will try to read the records using payoutRecords.find(Filter.isNotNull("name"), you will get an empty list.

Configuration

Payout Record Attribute Columns Metadata

You can also rename and customize the Payout Record’s attributeX fields. Even though it’s technically not required, it might be a good idea, because testing in Pricefx UI will be then much easier and more obvious.

Those given field names can be also utilized by Integration Manager, when it exports the Payout Records, so the integration setup will be somewhat easier to read.

Since you’re doing the field’s metadata setup via the Pricefx UI, remember to fetch the "Payout record attr (PYR)" metadata configuration from the partition to your project so that you can store it to Version Control.

Advanced Configuration

There’s optionally Advanced Configuration available for the Payout Records, so if you need some special settings, please refer to "Configure Payout Records" section of the documentation page Payout Records

If you’re using the Advanced Setting, remember to fetch the Advanced Option "payoutRecordsConfiguration" to your project and store it in version system.

Considerations

Possible important considerations which must be borne in mind.

Performance

Usage of Payout Records

Depending on the project, try to estimate, how many Rebate Records you would be using. If the estimated number of Rebate Records per Agreement will go over 100, then consider using Payout Records as a data storage, otherwise you might have performance issues.

If you only need one or a few 'records' per line item, you likely do not have to consider Payout Records.

Usage of Bulk Mode in the Logic

When you’re creating thousands of Payout Records, it will be faster, when you use the Bulk Mode - it’s designed to speed-up storing of high amounts of Payout Records.

However, there’s some overhead required by the Bulk Mode, so for lower amounts of Payout records, you will likely not use it. The best answer is always a performance test with the expected size of Payout Records.

References

Groovy API

PayoutRecordManager

Documentation

Payout Records

Knowledge Base

PYR – Payout Record