Create Partner Client and Revenue Claims

Definitions

`entity_type`

As Liberis provides financial products across multiple geographies, we have developed our own centralised understanding of business entities so simplify our workflows, such as eligibility.

Refer to Liberis Taxonomy to understand how to map your regional business entities.

`currency`

We accept only one currency as part of your integration. This will be aligned with you during onboarding.

For example:

EUR: for European companies
GBP: for British companies
USD: for United States companies
etc...

`time_period`

We accept two levels of granularity for time period:

Monthly
Daily

Monthly Revenue Claims

To send a revenue claim at a monthly level of granularity, the start and end dates should represent the start and end of the month the revenue claim is related to.
i.e.

start_date: 2025-01-01T00:00:00:000
end_date: 2025-01-31T23:59:59:999

Daily revenue Claims

To send a revenue claim at a daily level of granularity, the start and end dates should represent the start and end of the day the revenue claim is related to.
i.e.

start_date: 2025-01-01T00:00:00:000
end_date:2025-01-01T23:59:59:999

`total_amount` & `transaction_count`

At Liberis, we view revenue claims as either positively or negatively influencing revenue. Typically, in the world of transaction you might see a positive influencing transaction type being a sale and a negatively influencing transaction type being a return / chargeback

We simplified and extracted the concept of transactions and transaction types in our API and to indicate how a revenue claim influences a partner clients revenue, you should send total amount and transaction count in the same mathematical signage (i.e + or -) to indicate if this increases or decreases revenue.

For example, a positively influencing revenue claims (i.e a sale), would have these properties set with positive signage, as below:

total_amount: 100
transaction_count: 1000

A negatively influencing revenue claims (i.e a return or chargeback), would have both these properties set with negative signage, as below:

total_amount: -100
transaction_count: -1000

Valid `state` Values

There are several statuses that the state property can be:

Duplicate : The associated data item has been deemed a duplicate
Conflict : The associated data item has been deemed a conflict with another data item in the original request
Failed : The associated data item has failed validation
Completed : The associated data item has passed validation and was saved to our data store

Failure Statuses

Any data item which has a state of Duplicate, Conflict or Failed will not be saved to our data stores.

Duplicate

When a state has a value of Duplicate, it indicates one of two conditions has been met:

The associated data item is a perfect duplicate of another item in the original request, the first item in the original request was processed as unique and will provide its own state to indicate if Completed successfully and saved
The associated data item is a duplicate of a record we have already seen and saved to our data store

The validation_errors property will contain a string error which describes which one of the above conditions was met.

Conflict

When a state has a value of Conflict, it indicates:

The associated data item is a duplicate of another data item in the original request by the unique key partner_client_id - however the data differs in the duplicates.

When this condition is met, those data items that are deemed duplicates by unique key partner_client_id will all have a state of Conflict as we are unable to determine which one is valid to process and save.

Failed

When a state has a value of Failed, it indicates:

The associated data item failed our validation routines and was not saved.

The validation_errors property will contain a string error which describes which one of the above conditions was met.

It is recommended a client logs this information as it could indicate the data in the data item contains malformed values and as such invalid.

A retry of the failed data item can be actioned once the validation_errors have been addressed.