Loymax, 2026

Receipt history migration

During transition to Loymax Loyalty Program (LP), a Company purchase history can be imported into Loymax Loyalty. As a result, customers will see their purchase history from the previous loyalty program.

This article presents a simplified integration contract. The format is used when migrating historical receipts from external loyalty programs for display in personal accounts and CRM systems. The description focuses on the historical data migration scenario and does not cover all Loymax integration capabilities. Examples are provided in simplified form and reflect minimal valid structures.

Company data is transmitted to Loymax via a special utility and the messaging broker Apache Kafka. The utility converts the JSON file provided by the Company into a historical record model. The sender publishes the message to Kafka in the topic hist-items-records. The consumer HistoryItemsConsumer reads the message, converts it to protobuf format, and writes it to the History database. As a result, when accessing the Loymax history service via API in the Admin Panel, Personal Account, or Mobile App, the customer's receipt history is displayed.

View JSON file example for upload

{
"externalId": "34489de3-362c-49ed-9ac0-2ac982907d64", // Unique identifier of this history record. Required.
"dateTime": "2025-07-17T18:19:57Z", // Date/time of the event. Required.
"type": "PurchaseData", // Event type. Required.
"userId": null, // Identifier of the customer associated with the event. Optional.
"customerUid": "76bcd3cc-8825-46a6-9ca4-58c7a6cd5680", // Customer Uid. Required.
"identity": "2010000000304", // Additional data allowing identification of the event. Required.
"description": null, // Description. Optional.
"locationId": null, // Identifier of the store location where the purchase was made. Optional.
"partnerId": null, // Company identifier. Optional.
"brandUid": null, // Brand Uid. Optional.
"historyPurchase": {
"externalPurchaseId": "346501602", // External purchase identifier. Required.
"amount": 1600.47, // Purchase amount. Required.
"currencyUid": "718ae69b-76be-413f-ad19-7b7e02e4a438", // External currency identifier at the cash register (euros). Required. One currency can be passed for all purchases.
"merchantUid": "2cf2a75e-353a-9d28-7239-4e22d45fa191", // External store identifier. Required. One store can be passed for all purchases.
"deviceUid": "df99a5ed-fc31-d9bd-c594-d8d25261a437", // External cash register identifier. Required. One register can be passed for all purchases.
"chequeItems": [
   {
   "positionId": 1, // Receipt item position. Required. Filled as sequential number within each receipt.
   "description": null, // Description. Optional.
   "quantity": 1.000, // Quantity. Optional. If not provided, 0 will be displayed.
   "unit": null, // Unit of measure. Optional.
   "amount": 493.99, // Amount. Required.
   "itemId": "161029", // External product identifier. Optional.
   "discounts": [
     {
     "discountType": "CalculatedDiscount", // Discount type description. Required.
     "offerId": 40, // Internal offer identifier. Required.
     "offerVersionId": 81, // Internal version identifier of the offer. Required.
     "amount": 22.00, // Size of the discount provided in virtual currency. Required.
     "currencyId": 2, // Discount currency identifier. Required.
     "cashAmount": null // Amount in original currency (for payments). Required
    }
    ],
   "commonCode": null, // Common code of the item. Optional.
   "attributes": [], // Item attributes. Optional.
   "internalGoodId": 125 // Internal product identifier. Optional
  }
  ],
"withdraws": [
            {
             "moneyAmount": 69.60, // Amount in register currency. Required.
             "withdrawType": "Bonus", // Withdrawal type. Required.
             "description": null, // Operation description. Optional.
             "positionInfo": [ // Distribution of withdrawal across positions. Optional.
               {
                 "key": 1,
                 "value": 69.60
                }
              ],
             "amount": 69.60, // Amount in bonuses. Required.
    "currencyUid": "718ae69b-76be-413f-ad19-7b7e02e4a438" // External currency identifier. Required
           }
          ],
"rewards": [
   {
   "offerExternalId": "c4aa82c8-57f9-4ba6-9e41-3449d9db1fd7", // External offer identifier. Required.
   "description": null, // Reward description. Optional.
   "positionInfo": { // Distribution of reward across positions. Optional.
    "1": 22.00
    },
   "amount": 22.00, // Preference amount. Required.
   "rewardType": "Discount", // Preference type. Required.
   "currencyUid": "718ae69b-76be-413f-ad19-7b7e02e4a438" // External currency identifier. Required
  }
  ],
"isRefund": false, // Whether the purchase is a return. Optional. If not a return, value should be: false.
"chequeNumber": "H55052486709-170723", // Receipt number. Required.
"chequeAdditionalAttributes": [], // Information about items in the receipt. Optional.
"state": "Confirmed", // Purchase state. Required. Always pass value: Confirmed.
"additionalParams": {}, // Additional purchase parameters. Optional.
"pays": [
   {
   "id": 2, // Internal payment method identifier. Optional.
   "name": "Unknown", // Payment method name. Optional.
   "logicalName": "Unknown", // Logical name of the payment method. Optional. Value must match the LogicalName of the payment method created in the System.
   "amount": 1600.47, // Amount. Optional.
   "description": "Unknown" // Description. Optional
  }
  ],
"activities": [], // Activities. Optional.
"deviceEmulation": false, // Indicator whether the purchase was made on a test register. Optional. Value: false.
"operations": [], // Operations. Optional.
"coupons": [], // Coupons. Optional.
       "completeTime": "2025-07-17T18:19:57Z" // Purchase completion date. Optional
},
   "withdraws": [
   {
   "amount": -62.81,
   "withdrawType": "Withdraw",
   "currencyUid": "1f24174f-bfdb-4019-a3e7-4fb088b4a7a7"
   }
],
"rewards": [
   {
   "offerExternalId": "8825a082-468f-43fd-8171-52bfeb4f74a9",
   "positionInfo": {
    "1": 13.45,
    "2": 41.55
    },
   "amount": 55.00,
   "rewardType": "Bonus",
   "currencyUid": "1f24174f-bfdb-4019-a3e7-4fb088b4a7a7"
   }
],
"eventDateTime": 0, // File upload date and time. Required. Fill current date in ticks.
"loyalityUid": null, // External Loyalty Program identifier. Required.
"historyVersion": "V2", // History record version information. Required. Should be filled with value: V2.
"source": "true" // Record source information. Required. When saving data from Loymax loyalty system, leave this field empty. If the field is filled with any value other than an empty string or null, the history record is marked with Imported=true.
}

Data processing speed

The size of the data batch processed by the utility is fixed and equals 100. The optimal batch size for the HistoryItemsConsumer consumer is 1000. The processing time per message reaches 0.36 ms. Increasing the batch size in consumer settings increases processing time: 0.52 ms per message at a batch size of 10,000. Parallel operation of the utility and consumer reduces processing time to 0.22 ms per message.

Types of purchases to import

Purchase without detailed discounts and bonus points	Receipt with item composition and total amount without revealing discount, accrual, and deduction mechanics.
Purchase with line-item discounts	Receipt where applied discounts are recorded for individual items.
Purchase with line-item bonus points (with multi-currency support)	Receipt where bonus accruals are reflected for specific items.
Purchase with bonus points deduction	Receipt where the customer used bonus points to pay part of the purchase.
Separate accrual or deduction operations without a purchase	Bonus operations not linked to a specific receipt (e.g., manual corrections or expiration).

Structure of transmitted data

When transmitting purchase data, a single structure is used, including the following logical blocks:

General information about the purchase event.
Data about the purchase itself.
Receipt composition (item positions).
Discounts, accruals, and deductions (if applicable).
Payment information (if necessary).
Additional attributes and auxiliary data (optional).

Each of the above blocks is described below, specifying required and optional parameters.

Minimum required parameters are marked as required.
Optional fields are either left unfilled or filled with default values.

Field	Required	Data Type	Description
externalId	Required	Guid	Unique identifier of this history record
DateTime	Required	DateTime	Date and time of the event
Type	Required	string	Event type
UserId	Optional	int	Identifier of the customer associated with the event
CustomerUid	Required	Guid	Internal customer identifier, unique within the System
Identity	Required	string	Additional data allowing identification of the event. Fill with customer card number
Withdraw	Optional	WithdrawDataViewModel	Deduction (manual)
Reward	Optional	RewardDataViewModel	Accrual (manual)
Description	Optional	string	Description for display in history
LocationId	Optional	Guid	Point of sale location identifier where the purchase was made. Not recommended to fill
PartnerId	Optional	Guid	Company identifier, constant
BrandUid	Optional	Guid	Uid of the brand where the purchase occurred, often a constant
HistoryPurchase	Required	HistoryPurchaseDataViewModel	Historical purchase data. See HistoryPurchaseDataViewModel model below
EventDateTime	Required	long	File upload date and time. Fill current date in ticks
LoyalityUid	Required	Guid	External Loyalty Program identifier, constant
historyVersion	Required	HistoryVersionType	Information about the history record version (database table where data from the uploaded file is written). Should be filled with value: V2
source	Required	string	Record source information. When saving data from Loymax, leave this field empty. When importing external data, fill with any value, then the history record is marked with Imported=true.

Below the nested models for required fields of the general structure are listed and described. These also include both required and optional fields.

- Data processing speed
General purchase information: HistoryPurchaseDataViewModel

General purchase information: HistoryPurchaseDataViewModel

Field	Required	Data Type	Description
ExternalPurchaseId	Required	string	External purchase identifier
Amount	Required	decimal	Purchase amount after discounts
CurrencyUid	Required	string	External POS currency identifier (default POS currency: euros). One currency can be passed for all purchases
MerchantUid	Required	Guid	External point of sale identifier. One point of sale can be passed for all purchases
DeviceUid	Required	Guid	External POS identifier. One POS terminal can be passed for all purchases
ChequeItems	Required	HistoryChequeItemViewModel	Information about items in the receipt. See HistoryChequeItemViewModel model below
Withdraws	Required	WithdrawDataViewModel	Deductions within the purchase. See WithdrawDataViewModel model below
Rewards	Required	RewardDataViewModel	Accruals within the purchase. See RewardDataViewModel model below
IsRefund	Optional	bool	Whether the purchase is a refund. If no refunds, value: false
ChequeNumber	Required	string	Receipt number
ChequeAdditionalAttributes	Optional	ChequeAdditionalAttributeViewModel	Information about additional receipt attributes. Not recommended to transmit
State	Required	OperationState	Purchase state. Always pass value: Confirmed
AdditionalParams	Optional	string	Additional purchase parameters
Pays	Optional	PayModel	Payment methods. Fill if needed to specify what portion was paid with POS currency (euros)
Activities	Optional	Activity	Activities. Not recommended to transmit
DeviceEmulation	Optional	bool	Indicator whether the purchase was made on a test POS terminal. If transmitted, value always: false
Operations	Optional	PurchaseOperation	Operations
Coupons	Optional	Coupon	Coupons
ExternalPurchaseUid	Optional	string	Purchase identifier

Fields Withdraws and Rewards in the model are marked as required, despite potentially being empty arrays.
Field IsRefund is used to transmit refunds during migration (value true if transmitted).

Receipt item information: HistoryChequeItemViewModel

Field	Required	Data Type	Description
PositionId	Required	int?	Receipt position. Filled as sequential number within each receipt
Description	Optional	string	Description
Quantity	Optional	decimal	Quantity. If not passed, 0 will be displayed
Unit	Optional	string	Unit of measure
Amount	Required	decimal	Amount after discount deduction
ItemId	Optional	string	External product identifier (article)
Discounts	Required (conditional)	Discount	Discounts provided on receipt positions. Required if line-item detail is needed. See Discount model below
commonCode	Optional	string	Common code of the item
attributes	Optional	string	Item attributes. Not recommended to transmit
internalGoodId	Optional	int	Internal product identifier

Preference model: Discount

This model is used only when line-item discount detail is required (discount detail/payment detail/bonus points detail) and is included in the HistoryChequeItemViewModel model.

Field	Required	Data Type	Description
DiscountType	Required	PositionDiscountType	Type of preference provided. See PositionDiscountType model below
OfferId	Required	int	Internal offer identifier. Value must not equal 0. Pass identifier of a offer specifically created in the System; one can be created and passed as a constant
OfferVersionId	Required	int	Internal version identifier of the offer. Value must not equal 0. Pass identifier of a offer version specifically created in the System; one can be created and passed as a constant
Amount	Required	decimal	Amount of preference provided in virtual currency (if preference type: CalculatedCashback/PartnerCashback or CalculatedPayment) or in POS currency (if preference type: CalculatedDiscount/PartnerDiscount)
CurrencyId	Required	int?	Preference discount currency identifier. Must pass a currency that actually exists in the System: monetary or any virtual currency
CashAmount	Required	decimal?	Discount amount in POS currency (if preference type: CalculatedPayment). Do not fill if preference type: CalculatedCashback

Type of preference provided: PositionDiscountType

One of the specified values below must be passed if the Discount model is transmitted (see above).

Value	Name	Description
CalculatedCashback	Deferred bonus points	bonus points
CalculatedDiscount	Discount	Direct discount
PartnerDiscount	Partner discount	External/POS discount (passed from the point of sale POS terminal)
PartnerCashback	Partner bonus points	External/POS bonus points (passed from the point of sale POS terminal)
PositionCharge	Bonus points accrual	Bonus points accrual. This value is not used
CalculatedPayment	Payment	Deduction of bonus points for purchase

Deduction information: WithdrawDataViewModel

This model is used to transmit line-item deductions within a purchase in HistoryPurchaseDataViewModel, required to fill, and also for manual deductions in the root object (field Withdraw), filling optional.

Field	Required	Data Type	Description
MoneyAmount	Required	decimal?	Amount in POS currency (euros)
Description	Required	string	Operation description
PositionInfo	Optional	int, decimal	Distribution of deduction across positions
Amount	Required	decimal	Amount in bonus points
WithdrawType	Required	WithdrawType	Deduction type. See WithdrawType model below
CurrencyUid	Required	string	External virtual currency identifier

Deduction types: WithdrawType

One of the specified values below must be passed if the WithdrawDataViewModel model is transmitted (see above).

Value	Name	Description
Bonus	Bonuses	Bonus points deduction
Withdraw	Deduction	Deduction as a separate operation type
Expiration	Expiration	Bonus points expiration

Accrual information: RewardDataViewModel

This model is used to transmit accruals within a purchase in HistoryPurchaseDataViewModel, required to fill, and also for manual accruals in the root object (field Reward), filling optional.

Field	Required	Type	Description
OfferExternalId	Required	string	External offer identifier
Description	Required	string	Detailed description specifying this accrual operation
PositionInfo	Optional	int, decimal	Distribution of accrual across positions (position number, amount)
Amount	Required	double?	Preference amount
RewardType	Required	RewardType?	Accrual type. See RewardType model below
CurrencyUid	Required	string	External virtual currency identifier (if accrual type: Bonus or Charging) or POS currency (if accrual type: Discount)

Accrual type: RewardType

One of the specified values below must be passed if the RewardDataViewModel model is transmitted (see above).

Value	Name	Description
Bonus	bonus points	Bonus points
Discount	Discount	Discount
Charging	Accrual	Additional bonus points accrual (within receipt, but not linked to positions)

Created 2026/04/10 05:57
Last edited 2026/04/10 08:48

News
Updates
Tag cloud
Glossary
Site

Navigation