> For the complete documentation index, see [llms.txt](https://help.openloyalty.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.openloyalty.io/main-features/imports-exports/imports/sample-import-files/sample-import-files.md).

# 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

{% file src="/files/IRWvsyOVnMA8AW9h3CoB" %}

{% file src="/files/pO1q2lfquWu6U3CUpjzQ" %}

{% tabs %}
{% tab title="XML" %}
{% code title="transactions-import-sample.xml" %}

```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>
```

{% endcode %}
{% endtab %}

{% tab title="JSON" %}
{% code title="transactions-import-sample.json" %}

```json
[
  {
    "documentNumber": "TX-2024-001",
    "purchasePlace": "Store A",
    "purchaseDate": "2024-06-15T10:30:00+02:00",
    "documentType": "sell",
    "items": [
      {
        "sku": {
          "code": "SKU-12345"
        },
        "name": "Premium Widget",
        "quantity": 2,
        "grossValue": 49.99,
        "category": "Electronics"
      }
    ]
  }
]
```

{% endcode %}
{% endtab %}
{% endtabs %}

### Field reference

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

### Important notes

{% hint style="warning" %}
**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.
{% endhint %}

{% hint style="info" %}
**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.&#x20;
{% endhint %}

***

### 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

{% file src="/files/oC30htwsJBUhT4EHbTzn" %}

{% code title="transaction-match-sample.xml" %}

```xml
<?xml version="1.0" encoding="UTF-8"?>
<matches>
  <match>
    <documentNumber>TX-2024-001</documentNumber>
    <customerEmail>jane.doe@example.com</customerEmail>
  </match>
  <match>
    <documentNumber>TX-2024-002</documentNumber>
    <customerLoyaltyCardNumber>CARD-002</customerLoyaltyCardNumber>
  </match>
  <match>
    <documentNumber>TX-2024-003</documentNumber>
    <customerPhoneNumber>+1234567890</customerPhoneNumber>
  </match>
</matches>
```

{% endcode %}

#### Match field reference

<table><thead><tr><th width="243.75">Field</th><th width="181.47265625">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>documentNumber</code></td><td>Yes</td><td>The transaction's document number (must already exist in the system)</td></tr><tr><td><code>customerEmail</code></td><td>One of these three</td><td>Member's email address</td></tr><tr><td><code>customerLoyaltyCardNumber</code></td><td>One of these three</td><td>Member's loyalty card number</td></tr><tr><td><code>customerPhoneNumber</code></td><td>One of these three</td><td>Member's phone number</td></tr></tbody></table>

{% hint style="info" %}
**You do not need to run a match import after every transaction import.**&#x20;

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.
{% endhint %}

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

{% content-ref url="/pages/t9GVcnOzM2bKY9lB1FwH" %}
[Matching Transactions with Members](/main-features/transactions/matching-transactions.md)
{% endcontent-ref %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://help.openloyalty.io/main-features/imports-exports/imports/sample-import-files/sample-import-files.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.