> 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/implementation-guide/module-checklists/transactions.md).

# Transactions

Sending purchases and returns from e-commerce and stores to Open Loyalty so members earn — with the API calls, webhooks and checks for each step.

Transactions are purchases and returns. When one reaches Open Loyalty and matches a member, purchase or return campaigns decide what the member earns or loses. This page covers sending them reliably from e-commerce and stores.

For non-purchase activity — reading an article, scanning a code, registering a device — use [custom events](https://help.openloyalty.io/members-and-activity/custom-events) instead. For the Admin Panel side, see [Transactions](https://help.openloyalty.io/members-and-activity/transactions) and the [purchase transaction](https://help.openloyalty.io/campaigns/campaigns/campaigns-and-referral-campaigns/creating-campaigns/trigger-types/purchase-transaction) campaign trigger.

## Who does what

| Area                           | Responsibility                                                                                                                                                                                                                                                                                        |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Admin Panel**                | [Channels](https://help.openloyalty.io/members-and-activity/transactions/channels), purchase and return campaigns, [transaction item filters](https://help.openloyalty.io/campaigns/campaigns/campaigns-and-referral-campaigns/creating-campaigns/transaction-item-filters) for SKU or category rules |
| **Integration layer**          | Turns orders and receipts into transactions, sends them once, retries safely, sends returns linked to the original sale, matches guest orders later                                                                                                                                                   |
| **E-commerce platform / POS**  | Reports completed orders, receipts and returns with the customer's identifier                                                                                                                                                                                                                         |
| **CRM / marketing automation** | Receives balance changes through webhooks and tells the member what they earned                                                                                                                                                                                                                       |

## Design decisions

| Decision                | Options                                                          | Recommendation                                                                                                                                                                                                                                                                                                              |
| ----------------------- | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| When to send a purchase | At order placement, payment, shipment or after the return window | Send it when the order can no longer be cancelled without a return — usually at payment or shipment. If returns are frequent, consider the wallet's [unit pending method](https://help.openloyalty.io/members-and-activity/wallets/wallet-types-and-configuration) so points become spendable only after the return window. |
| Document number         | Order ID, invoice number, receipt number                         | A number that is unique per tenant across all channels. If two channels can produce the same number, prefix it (`WEB-1001`, `STORE12-1001`).                                                                                                                                                                                |
| How much item detail    | Totals only, or every line with SKU, category, maker             | Send lines with SKU and category if any campaign rewards specific products, now or later.                                                                                                                                                                                                                                   |
| Guest purchases         | Ignore, or send unmatched and match later                        | Send them unmatched; the member can claim them after registering.                                                                                                                                                                                                                                                           |
| Earning on returns      | Leave points, or deduct them                                     | Configure return campaigns that mirror your purchase campaigns.                                                                                                                                                                                                                                                             |

## Recommended flow

{% stepper %}
{% step %}

### Configure (Admin Panel)

Create a channel per sales channel (web shop, app, each store group) and note their IDs. Set up purchase campaigns and, if points should be taken back, matching [return campaigns](https://help.openloyalty.io/campaigns/campaigns/campaigns-and-referral-campaigns/creating-campaigns/trigger-types/return-transaction).
{% endstep %}

{% step %}

### Send purchases

`POST /api/{storeCode}/transaction` with `header.documentType = sell`, a unique `header.documentNumber`, `header.purchasedAt`, `channelId`, the member identifier in `customerData` (e.g. `loyaltyCardNumber`) and the `items`. Open Loyalty matches the member and runs purchase campaigns.
{% endstep %}

{% step %}

### Retry safely

Document numbers are unique per tenant. If a request times out, resend it with the same document number: a `400` with an error on `header.documentNumber` ("document number should be unique") means the first attempt was recorded — treat it as success.
{% endstep %}

{% step %}

### Send returns

`POST /api/{storeCode}/transaction` with `documentType = return`, its own `documentNumber`, the returned `items`, and `linkedDocumentNumber` set to the original sale. A return whose linked sale doesn't exist is rejected — make sure the sale was sent first.
{% endstep %}

{% step %}

### Match guest purchases

Send guest orders without member identifiers; they're stored as *Not matched*. When the customer registers or logs in and claims the order, call `POST /api/{storeCode}/transaction/assign` with the `transactionDocumentNumber` and the member's identifier. Campaigns run at that point. See [Matching transactions with members](https://help.openloyalty.io/members-and-activity/transactions/matching-transactions).
{% endstep %}

{% step %}

### Tell the member

Subscribe to `WalletBalanceUpdated` (or `TransactionRegistered` if you message on the purchase itself) and pass it to CRM or marketing automation.
{% endstep %}
{% endstepper %}

## Sequence diagrams

<figure><img src="https://226878483-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZ4Fuoa1PTF0DrNTgjzJu%2Fuploads%2Fgit-blob-188fddca9f018fb6ea93706f36b441b1b17aaa4a%2Fig-transactions-purchase.png?alt=media" alt="The e-commerce platform or POS reports a completed order. The integration layer sends it to Open Loyalty as a sell transaction with the order number as document number, the member&#x27;s loyalty card number, the items and the channel. Open Loyalty matches the member, runs purchase campaigns and adds units, returns the transactionId and sends a WalletBalanceUpdated webhook, which is passed to CRM. A retry with the same document number returns 400 because it is already recorded." width="728"><figcaption><p>Purchase</p></figcaption></figure>

<figure><img src="https://226878483-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZ4Fuoa1PTF0DrNTgjzJu%2Fuploads%2Fgit-blob-50ce1b65fb3c72dad1163caa68b2f05e3f83db87%2Fig-transactions-return.png?alt=media" alt="The channel reports returned items. The integration layer sends a return transaction with its own document number and the original order number as linked document number. Open Loyalty checks the original sale exists and runs return campaigns, for example deducting the units earned. Tiers, campaign limits and counters from the original purchase are not reverted." width="645"><figcaption><p>Return</p></figcaption></figure>

<figure><img src="https://226878483-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZ4Fuoa1PTF0DrNTgjzJu%2Fuploads%2Fgit-blob-1951b420d7fe66d66345ad6bedbc6344730c260c%2Fig-transactions-matching.png?alt=media" alt="A guest order is sent without member identifiers and stored as not matched, with no units. Later the customer claims the order; the integration layer calls transaction assign with the document number and the member&#x27;s loyalty card number, and Open Loyalty matches the transaction and runs purchase campaigns." width="621"><figcaption><p>Guest purchase matched later</p></figcaption></figure>

{% hint style="info" %}
Returns are a separate flow. A return campaign can deduct units, but it doesn't revert a tier, campaign limits or counters that the original purchase affected. See [Returns and cancellations](https://help.openloyalty.io/faq/returns-and-cancellations).
{% endhint %}

## Go-live checklist

### Admin Panel

* [ ] A channel exists for every sales channel, and the integration sends the right `channelId`.
* [ ] Purchase campaigns are active and tested with real basket examples.
* [ ] Return campaigns mirror the purchase campaigns, if points should be taken back.
* [ ] Item filters cover every SKU or category rule the programme promises.

### Integration layer

* [ ] Every transaction has a document number that is unique across all channels.
* [ ] Timeouts are retried with the same document number, and the duplicate `400` is treated as success.
* [ ] Returns carry `linkedDocumentNumber` and are sent only after their sale.
* [ ] `purchasedAt` is the real purchase time, with timezone.
* [ ] Guest orders are sent unmatched and assigned when the customer claims them.
* [ ] Failed transactions are logged with their payload and replayed after fixes.

### Channels and CRM

* [ ] The member sees what they earned, from the balance webhook or by reading the wallet.
* [ ] CRM messages use the webhook, not a guess made at checkout.

### Validation

* [ ] A purchase earns the expected units for a few typical baskets.
* [ ] Sending the same order twice earns once.
* [ ] A full and a partial return deduct what the return campaigns say.
* [ ] A return for an unknown order is rejected and logged.
* [ ] A guest order claimed after registration earns once.

## Key endpoints

* `POST /api/{storeCode}/transaction` — [Add a transaction](https://help.openloyalty.io/api-reference/transactions/add-a-transaction)
* `POST /api/{storeCode}/transaction/assign` — [Match the transaction](https://help.openloyalty.io/api-reference/transactions/match-the-transaction)
* `GET /api/{storeCode}/transaction` — [Get transactions list](https://help.openloyalty.io/api-reference/transactions/get-transactions-list), filtered e.g. by `customerData:loyaltyCardNumber`
* `GET /api/{storeCode}/transaction/{transaction}` — [Get transaction's details](https://help.openloyalty.io/api-reference/transactions/get-transactions-details)

**Webhooks:** [TransactionRegistered](https://apidocs.openloyalty.io/#tag/Webhook-event/operation/TransactionRegistered), [TransactionAssignedToCustomer](https://apidocs.openloyalty.io/#tag/Webhook-event/operation/TransactionAssignedToCustomer), [WalletBalanceUpdated](https://apidocs.openloyalty.io/#tag/Webhook-event/operation/WalletBalanceUpdated)

{% hint style="warning" %}
**Common pitfalls**

* Two channels using the same order numbers: the second channel's orders are rejected as duplicates.
* Sending a return before its sale, or without `linkedDocumentNumber`: it's rejected.
* Retrying with a new document number after a timeout: the member earns twice.
* Sending totals only, then launching a product campaign: older transactions can't qualify.
* Expecting a return to undo a tier upgrade or a campaign limit: it doesn't.
  {% endhint %}


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://help.openloyalty.io/implementation-guide/module-checklists/transactions.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
