Transactions

How to import transactions and match them to members in Open Loyalty using XML or JSON files.

Use the transaction import to load purchase or return data in bulk. This is commonly used during initial migration or when integrating offline sales data.

File format: XML or JSON

Sample files

5KB

Transactions Import.xml

Open

4KB

Transactions Import.json

Open

XML

transactions-import-sample.xml

<?xml version="1.0" encoding="UTF-8"?>
<transactions>
  <transaction>
    <documentNumber>TX-2024-001</documentNumber>
    <purchasePlace>Store A</purchasePlace>
    <purchaseDate>2024-06-15T10:30:00+02:00</purchaseDate>
    <documentType>sell</documentType>
    <items>
      <item>
        <sku>
          <code>SKU-12345</code>
        </sku>
        <name>Premium Widget</name>
        <quantity>2</quantity>
        <grossValue>49.99</grossValue>
        <category>Electronics</category>
      </item>
    </items>
  </transaction>
</transactions>

JSON

Field reference

Field	Required	Description
documentNumber	Yes	Unique transaction identifier
purchasePlace	No	Store or location name
purchaseDate	Yes	ISO 8601 timestamp with timezone (e.g., 2024-06-15T10:30:00+02:00)
documentType	Yes	sell for purchases, return for returns
items	Yes	At least one line item
items.sku.code	Yes	Product SKU code
items.name	Yes	Product name
items.quantity	Yes	Number of items
items.grossValue	Yes	Total gross value
items.category	No	Product category

Important notes

Always include a timezone offset in purchaseDate (e.g., +02:00 or Z for UTC). Without it, the timestamp may be interpreted incorrectly, leading to campaigns not triggering or points being calculated for the wrong period.

Imported transactions are automatically matched to existing members. When a transaction is imported, Open Loyalty checks whether a corresponding member profile already exists. If a match is found, the transaction is linked to that member automatically.

---

Matching unmatched transactions

The Transaction match import is only needed when you have unmatched transactions in the system — whether imported or created via API — that were not automatically linked to a member. This can happen when transactions were recorded before the corresponding member profiles existed, or when the automatic matching could not resolve the member.

Use this import to manually associate unmatched transactions with members by document number.

File format: XML

Sample file

247B

Transactions Match Import.xml

Open

transaction-match-sample.xml

<?xml version="1.0" encoding="UTF-8"?>
<matches>
  <match>
    <documentNumber>TX-2024-001</documentNumber>
    <customerEmail>[e-mail]</customerEmail>
  </match>
  <match>
    <documentNumber>TX-2024-002</documentNumber>
    <customerLoyaltyCardNumber>CARD-002</customerLoyaltyCardNumber>
  </match>
  <match>
    <documentNumber>TX-2024-003</documentNumber>
    <customerPhoneNumber>[phone]</customerPhoneNumber>
  </match>
</matches>

Match field reference

Field	Required	Description
documentNumber	Yes	The transaction's document number (must already exist in the system)
customerEmail	One of these three	Member's email address
customerLoyaltyCardNumber	One of these three	Member's loyalty card number
customerPhoneNumber	One of these three	Member's phone number

You do not need to run a match import after every transaction import.

Imported transactions are automatically linked when a corresponding member profile exists.

The Transaction match import is a tool for resolving unmatched transactions that could not be linked automatically.

To find out more, please refer to the article below:

Matching Transactions with Members