Working with Transactions

Sending transactional data to Omneo introduces transactional based aggregations to profiles, and also adds transactional history and recommendations in Profile Portal and Clienteling.

Before you begin

• Review the Authentication to become familiar with authentication with Omneo.
• Become familiar with the Transactions API. This is how we import transactions into Omneo.
• Determine what fields you wish to sync with Omneo.
  Omneo has some required fields, but there are many optional fields that are a part of a transactions.
  The more data you can provide to Omneo, the better the experience.

For a guide on testing with Omneo, check out the Getting started with Postman guide.

📘

For the best experience, we recommend syncing transactions with Omneo immediately after they are completed.
Omneo should only contain completed transactions.
At this time draft, partial paid or and other incomplete transactions should not be synced

What is covered in this guide

1. Required data for transactions.
2. Adding transactions
3. Updating transactions
4. Deleting transactions
5. Managing Transaction Items
6. Bulk creating transactions

Getting Started

Planning your data dictionary.

When approached with the task of adding transactions to Omneo, planning is a major part of the process.
Start up a mapping process in a spreadsheet or flow chart mapping out each transaction field available to you in your local system.
Following this, match this with the fields available in our payload defined in Add Transaction.
The goal being, to decide what data you wish to carry over to Omneo, and what fields you wish to map it to.

👍

Don't know the Omneo Profile ID?

Not a problem! By specifying a profile_id_handle you can change the way Omneo searches for profiles. Change this field to 'email', and Omneo will search for an email specified in the profile_id. Change this field to any other string, and Omneo will search for a profile identity matching that handle, and matching the value specified in the profile_id field.

A full explanation of this method can be found in the Transactions API docs

Planning your transmission method.

Simply put, Omneo requires data to be sent in a JSON payload, to one of its Transaction API endpoints. You will need to decide the best way to send the data in the required format.
Common solutions could be:

Client system webhooks, later transformed via a proxy service to fit with Omneo

Proxy services could be developed by your developers to reformat your systems webhooks into our format. This could even be a 3rd party service such as Zapier or Integromat.

Custom application to poll or detect transactions being placed, built specifically to sync transactions with Omneo

After you've determined the available transaction data you can sync to Omneo, you'll need to push it to Omneo via the Add Transaction API.

Anatomy of a transaction

A transaction can be broken down into Header and Item level information.
The header information being detail regarding the entire transaction,
and the Item information being detail regarding individual items on the sale.
Transactions also carry important information regarding the location, time and date the transaction was made. Additional information such as the staff member and payments can also be included.
All of this data has an impact on Omneo, influencing profile aggregations.
Some header level information is shown to the customer such as total, location, email, items, staff and receipt_ref.

About Transaction Items

Transaction items are provided as a part of the initial Add Transaction payload.
You also have the option to add a

📘

Fields you don't want to miss!

Although not required fields.
location_id: The omneo location ID where the transaction took place
external_id: The transaction id in your external client system
receipt_ref: The customers receipt #. This is usually the number the customer knows, and how they refer to the transaction - very important!
staff_id: The staff member the customer was served by.
profile_id: Attribute the transaction to a profile in Omneo. Omneo allows anonymous transaction, but this is still - very important

Adding a Transaction

We'll assume that a transaction has taken place on the client system.
The payload is formatted as the below.
Providing this payload to Omneo will create our transaction!

You will need to substitute your profile_id with a real one from your system.
Specifying this field attributes the transactions to an Omneo Profile .
Edit the data below however you like.
and provide the payload in the body of your request to Add Transaction

JSON

{
    "total": 18,
    "transacted_at" : "2021-01-01 00:09:20",
    "external_id" : "10333",
    "location_id" : 2,
    "timezone" : "Australia/Melbourne",
    "tags" : ["simple", "store"],
    "payments" : ["EFTPOS", "TESTING"],
    "receipt_email": "[email protected]",
    "receipt_is_email": false,
    "receipt_ref" : "659",
    "staff_id" : 1993,
    "items": [
        {
            "name": "Product 1",
            "product_variant_id": 333729,
            "quantity": 1,
            "price_current": 10,
            "price_sell": 9,
            "is_void": false,
            "price_original": 10,
            "price_margin": 1
        },
          {
            "name": "Product 2",
            "product_variant_id": 325121,
            "quantity": 1,
            "price_current": 10,
            "price_sell": 9,
            "is_void": false,
            "price_original": 10,
            "price_margin": 1
        }
    ],
    "profile_id": "9332c9b2-e31c-4d49-8ec3-62a9466d339c"
}

After calling the API, navigate in your CX Manager to the profile,
you should now see the transaction listed against the profile. in "Recent Transactions"

Updating a Transaction

You can make adjustments to a transaction by using the Edit Transaction endpoint.
Specify the id of your recently created transaction in the URL of this endpoint, and provide a similar payload to the below.
Only fields included in the payload will be updated.

In the below example, I only want to update two fields
Provide this to the Edit Transaction endpoint to update the transaction.

JSON

{
    "total": 15,
    "external_id" : "0000113"
}

View the same transaction in your CX manager and you'll notice these values have changes!

Update-Create a transaction.

The two steps we've just completed above can be done in one easy API call.
The above method can be cumbersome, the Create or Update a Transaction allows developers to perform the two functions in one call.
This could be the ideal situation if a reliable id or external_id are provided in the payload.
The method searches for transactions matching the external_id and then id and if one is found, the payload is used to update the transaction.
If no matching transactions are found, a new transaction is created instead.

Delete a transaction

It is not recommended to delete any transactions.
Transactions could be updated with the is_void parameter instead to void the transaction.
Few scenarios require the hard deletion of transactions out of Omneo, but if this is required due to error or testing, this is possible via the Delete Transaction endpoint.

To delete a transaction, provide the id of the transaction to the Delete Transaction endpoint. The transaction will then be deleted.

Reading Individual transactions

Similar to the above, providing the transaction id to the Read Transaction payload's URL will return the response of a single transaction. This can be useful when reading a customers individual transaction. Simply make a GET request to the endpoint, and the transaction is returned.

Reading all transactions

If you need to get multiple transactions, a simple GET request to the Browse Transactions. By default, this will return all transactions in your Omneo instance.
Omneo has a list of available filters in the Browse Transactions URL, that allow developers to further refine their results.
This is essentially a way to filter down the list of transactions to ones that meet the filters criteria.

Further information on how to apply these filters to the end of the endpoint's URL can be found in the documentation links above.

Adding Line Items to transactions

Line items can be added to a transaction after it has been created.
The transaction total will not be adjusted.

To do this, copy the a single item from the above payload, and use it when calling the Add Transaction Item endpoint.
Provide the transaction id in the request URL, and the same payload used for a single item in the above array.
and example could be:

JSON

{
    "name": "Product TEST AD",
    "product_variant_id": 1,
    "quantity": 1,
    "price_current": 10,
    "price_sell": 9,
    "is_void": false,
    "price_original": 10,
    "price_margin": 1
}

Once the request is completed, the item will be added as a line item of the specified transaction.

Bulk Creating Transactions.

It is common when onboarding with Omneo, that large volumes of historical transactions need to be imported. The Add Transaction may not suit the needs of this scenareo, as it processes each transaction immediately, and sends back a response. This endpoint is good for live transactions, where immediate feedback is needed, but is not great when it comes to importing millions of transactions at once.

The Queue Transaction endpoint solves this problem by providing developers with the ability to add transaction creation to a batch processing queue.
This endpoint accepts the same as the Add Transaction endpoint. With the only main difference being the request is submitted to a batch processing queue.

To implement this, developers will need to loop through transactions on their external system, and send each transaction individually using this endpoint. These transactions will be added to the batch queue, and be processed subject to the other jobs in the queue.

As each transaction is created or updated, the appropriate webhook will be triggered. Developers can use these webhooks to retrieve information about the created transactions.

Conclusion

This guide follows the process of creating, updating, and deleting transactions and transaction items.
The Omneo Business API can be used to manager all of the operations described above.
This guide is intended for developers who are seeking integrate transactions with Omneo, using these transactional API's. The methods described above are the base requirements for a importing transactions from an external system into Omneo.