Transactions

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

Transactions

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

Transactions Import Sample File.json

2KB

Open

Transactions Import Sample File.xml

3KB

Open

XML

transactions-import-sample.xml

<?xml version="1.0" encoding="UTF-8"?>
<transactions>
    <transaction>
        <header>
            <documentNumber>R123/13</documentNumber>
            <purchasePlace>Wrocław</purchasePlace>
            <purchasedAt>2024-08-14T15:52:01+00:00</purchasedAt>
            <documentType>sell</documentType>
            <labels>
                <label>
                    <key>test1</key>
                    <value>value1</value>
                </label>
            </labels>
        </header>
        <customerData>
            <name>John Doe</name>
            <email>[e-mail]</email>
            <nip>123-12-22-123</nip>
            <phone>4823123123</phone>
            <loyaltyCardNumber>12982332</loyaltyCardNumber>
            <address>
                <street>Bagnista</street>
                <address1>123</address1>
                <city>Wrocław</city>
                <country>PL</country>
                <province>Dolnośląskie</province>
                <postal>45-123</postal>
            </address>
        </customerData>
        <items>
            <item>
                <sku>SKU1</sku>
                <name>Item 1</name>
                <highPrecisionQuantity>3.255</highPrecisionQuantity>
                <grossValue>100</grossValue>
                <category>category1</category>
                <maker>maker</maker>
                <labels>
                    <label>
                        <key>test1</key>
                        <value>value1</value>
                    </label>
                </labels>
            </item>
        </items>
    </transaction>
</transactions>

JSON

transaction_with_one_item.json

[
    {
        "header": {
            "documentNumber": "R123/15",
            "purchasePlace": "Wrocław",
            "purchasedAt": "2024-08-14T15:52:01+00:00",
            "documentType": "sell",
            "labels": [{"key": "test1", "value": "value1"}]
        },
        "customerData": {
            "name": "John Doe",
            "email": "[e-mail]",
            "nip": "123-12-22-123",
            "phone": "4823123123",
            "loyaltyCardNumber": "12982332",
            "address": {
                "street": "Bagnista",
                "address1": "123",
                "city": "Wrocław",
                "country": "PL",
                "province": "Dolnośląskie",
                "postal": "45-123"
            }
        },
        "items": [
            {
                "sku": "SKU1",
                "name": "Item 1",
                "quantity": "1",
                "grossValue": "100",
                "category": "category1",
                "maker": "maker",
                "labels": [{"key": "test1", "value": "value1"}]
            }
        ]
    }
]

Field reference

Field	Required	Description
header.documentNumber	Yes	Unique transaction identifier
header.purchasePlace	No	Store or location name
header.purchasedAt	Yes	ISO 8601 timestamp with timezone (e.g. 2024-08-14T15:52:01+00:00)
header.documentType	Yes	sell for purchases, return for returns
header.labels	No	Optional list of custom key/value tags attached to the transaction
customerData	No	Identifies the member this transaction belongs to. Include at least one of email, phone, loyaltyCardNumber, or nip to have the transaction linked automatically
customerData.address	No	Optional structured address: street, address1, address2, city, province, postal, country
items	Yes	At least one line item
items.sku	Yes	Product SKU code (plain string)
items.name	Yes	Product name
items.quantity or items.highPrecisionQuantity	One of these	Number of units. Use quantity for whole units, or highPrecisionQuantity for fractional amounts (e.g. weight-based sales)
items.grossValue	Yes	Total gross value of the line item
items.category	No	Product category
items.maker	No	Manufacturer or brand name
items.labels	No	Optional list of custom key/value tags attached to the item

Important notes

Always include a timezone offset in purchasedAt (e.g. +00:00 or Z). 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 with customerData, Open Loyalty checks whether a corresponding member profile already exists using the identifiers provided. 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

Transactions Match Import.xml

247B

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