Payout Records - Handbook

Owned by Maroš Grman
Last updated: Sept 12, 2024 by Ioana Kocurova
6 min read

Introduction

This section describes a 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 customer solution.

Business Use Case

The customer needs to calculate the 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 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 needs 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

at 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)

    • logic you can 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 lot 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.

2nd level of calculations

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

When your solution needs 2 levels of calculation:

  • 1st level - summary calculations (possibly for group of customers, or groups of products )

  • 2nd 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 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 PayoutRecords

The flow of the Rebates is usually following:

  1. Design / Create Rebate Strategy (RBA)

  2. Accrue expected payouts as time passes (RR)

  3. 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 3 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, how 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 PayoutRecord

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 couple fields are built-in and for the rest you need to use the attributeX columns.

Figure 3. Detail of Entities used in Rebates, their fields and relations. This reflects the data in database, not the object model and it’s methods.

Types of Payout Record

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

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

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

  1. "Summary"

  2. "Detail"

  3. "Accrual Summary"

  4. "Accrual Detail"

  5. "Payout"

  6. 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 PayoutRecords will be linked to

  • via object PayoutRecordManager which is available via binding variable payoutRecords.

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

def rebateRecord = api.currentItem() payoutRecords.bulkLoadMode() //(1) //payoutRecords.delete() //(2) payoutRecords.add( "Payout", "${rebateRecord.id}-${productId}-${customerId}", [ startDate : rebateRecord.startDate, //(3) endDate : rebateRecord.endDate, //(3) payoutDate : rebateRecord.payoutDate, //(3) attribute1: customerId, attribute2: productId, attribute3: rebateValue, attribute4: currency, attribute5: rebatePct, attribute6: paymentPeriod, attribute7: rebateRecord.attribute2 ] ) payoutRecords.flush() //(4)

1

use if you’re generating huge amount of Payout Records

2

delete all PayoutRecords linked to the current Rebate Record. This is important, if you know, that it’s possible, that you’re going to create different set of the Payout Records during recalculation of the Rebate Record.

3

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.

4

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 PayoutRecord’s attributeX fields. Even though it’s technically not required, it’s likely a good idea, because testing in Pricefx UI will be then much easier and more obvious.

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

Since you’re doing the field’s metadata setup via 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 documentation page Payout+Records

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

Considerations

possible important considerations which must be bear 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 PayoutRecords, 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 needed by the Bulk Mode, so for lower amounts of Payout records, you will likely not use it. The best answer is always a test of performance with expected size of PayoutRecords.

References

Groovy API

Documentation

Knowledge Base

 

Found an issue in documentation? Write to us.

Â