Transactions

What is a transaction?

A transaction contains key information about a customer purchase, such as the Items, sale price, date and time stamps, and payment methods. Transactions influence different areas of Omneo such as Profile aggregations. Anonymous transactions can be claimed at a later date using Claim Transaction.
This allows the customer to attribute sales to their brand profile at a later date if they forgot to log in.

{
   "id":43,
   "external_id":60391123,
   "redemption":3,
   "profile_id":"08bae47-3333-49d2-9399-c2e87da3328d6",
   "location":3,
   "meta":null,
   "total":99.99,
   "total_original":110,
   "systems":[
      
   ],
   "rounding":10,
   "margin":31,
   "is_void":false,
   "transacted_at":"2021-01-27 23:00:00",
   "timezone":"Australia/Melbourne",
   "tags":[
      
   ],
   "items":[
      {
         "id":55,
         "external_id":null,
         "name":"test_prod",
         "transaction_id":43,
         "product_id":29259,
         "product_variant_id":129929,
         "sku":1012310,
         "variant_external_id":null,
         "is_void":false,
         "quantity":1,
         "price_current":99.99,
         "price_sell":99.99,
         "price_original":null,
         "price_margin":null,
         "price_tax":null,
         "discounts":null,
         "product_images":[
            
         ],
         "created_at":"2021-01-27 23:38:36",
         "updated_at":"2021-01-27 23:38:36"
      }
   ],
   "payments":null,
   "receipt_is_email":null,
   "receipt_ref":null,
   "claimed_at":null,
   "receipt_email":null,
   "staff":null,
   "currency_id":null,
   "currency_rate":null,
   "currency":null,
   "created_at":"2021-01-27 23:38:36",
   "updated_at":"2021-01-27 23:38:36"
}

Transaction Properties

Meta Fields

For any custom data required for your Omneo integrations, meta can be used to store your custom data as an object. These key value pairs can be modified as needed, and there is no limit to their naming or quantity.

Attribute

Description

id READ-ONLY INTEGER

A read only identifier for the transaction

profile_id
STRING

The profile_id of the linked Profile

  • or email/identity value when profile_id_handle specified

profile_id_handle
STRING

Specify to search a profile by email or identity. Further information onprofile_id_handle in below section

external_id
STRING

An 3rd party reference for the transaction. Usually the transaction reference as it appears in the client system

redemption
OBJECT

The redemption object returned from the specified redemption_id provided during the Add Transaction request.

redemption_id
INTEGER

The id of the redemption created using Add Reward or Point Redemption. Used to attach the redemption to a transaction.

location
OBJECT

The Location where the transaction was placed

location_id
STRING

Omneo first looks for a location with matching id If not found, Omneo will search for a location with a matching external_id if not found, Omneo will create a new transaction with matching external_id

currency
STRING

The currency of the transaction
Must be a valid currency configured in your Omneo portal

total
FLOAT

The total value of the sale

rounding
FLOAT

a $ value used when rounding the total value, this is usually cents and is can be used to round the total up to the nearest whole number.

tender
STRING

A simple string displaying the tender used on the transaction.

margin
FLOAT

The gross profit across the entire transaction.

deliver_at
DATE-TIME

The delivery date and time

transacted_at
DATE-TIME

The Date and time of the transaction

tags
ARRAY

An array of customised tags against the transaction

systems
ARRAY

An array of systems against the transaction
e.g ['pos','eftpos']

staff_id

The staff_id responsible for handling the transaction

payments
ARRAY

An array of payments used against this transaction.
example: [ { "eftpos" : 100, "cash": 20 } ][ { "eftpos" : 100, "cash": 20 } ]

total_original
FLOAT

The total original price of the transaction

timezone
STRING

The timezone the transaction was placed in

items
OBJECT

Transaction line items attached to this transaction

receipt_is_email
BOOLEAN

A boolean denoting whether the receipt was sent as an email

receipt_ref
STRING

The customer reference for the receipt.
This is usually the customers primary identifier for the transaction, and is printed on their receipt.

claimed_at
DATE-TIME

Date the transaction was claimed (if applicable)

receipt_email
EMAIL

The customer email address the receipt will be sent.

meta
OBJECT

All custom data to your Omneo implementation can go here. This can contain key value pairs. Some examples might be {"connote": 123, "shipping_date": "12-1-2022"}

Attaching Profile to transaction using Email or Identity.

In many cases, the external client system will have no knowledge of the omneo id.
attaching a profile_id_handle to the transaction payload, changes the way Omneo searches for profiles.

This field can be set to search by Profile Identity, or by profile email.

By setting theprofile_id_handle to 'email'
Specify the "email" of the Omneo Profile you wish to attach the sale to
in the profile_id field. Omneo will now search for a profile matching that email, and attach the transaction to it.
As part of your payload, this may look like:

{
 ...
"profile_id" : "[email protected]",
"profile_id_handle": "email"
 ...
}

By setting theprofile_id_handle to anything else
If this field is set to any other string, Omneo will look for a Profile with a Profile Identity handle of the value you've put in profile_id_handle, and with an identify value of the string you've specified in profile_id.
An example of this in action may look like:

{
 ...
"profile_id" : "ID123",
"profile_id_handle": "ap21"
 ...
}

In the above example, Omneo will search for a profile with an identity with a handle "ap21".
And a value of "ID123". If this is found, Omneo will attach this profile to the transaction.

With the above logic, it is possible to attach an Omneo profile to a transaction without knowing the ID.
If external client system ID's are stored against profiles as identities or if the profile email is unique between systems, this method can be used.

Event Context

The transaction context available in webhooks and targets.

{
   "id":20,
   "external_id":"3d12ass4s4ds11",
   "redemption_id":null,
   "redemption":null,
   "profile_id":"928bc629-8646-4d4b-808d-790fe6f334ae",
   "staff_id":"92c1f3e8-98ab-4344-8508-aa7e018cda5b",
   "staff" : {}, // Staff Context
   "profile":{}, // Profile Context
   "location_id":2,
   "location":{}, // Location Context
   "currency_id":null,
   "total":19.99,
   "is_void":false,
   "total_original":null,
   "currency_rate":null,
   "rounding":null,
   "margin":null,
   "meta":null,
   "deliver_at":null,
   "claimed_at":null,
   "transacted_at":"2021-04-16 03:45:20",
   "tags":[
      {
         "id":11,
         "handle":"simple",
         "created_at":"2021-04-23 02:04:38",
         "updated_at":"2021-04-23 02:04:38"
      },
      {
         "id":12,
         "handle":"tag",
         "created_at":"2021-04-23 02:04:38",
         "updated_at":"2021-04-23 02:04:38"
      }
   ],
   "systems":[],
   "items":[
      {
         "id":20,
         "profile_id":"928bc629-8646-4d4b-808d-790fe6f334ae",
         "transaction_id":20,
         "is_void":false,
         "is_transaction_void":false,
         "name":"Product 1",
         "quantity":1,
         "quantity_abs":1,
         "price_current":10,
         "price_sell":9,
         "price_original":10,
         "price_margin":1,
         "price_tax":null,
         "product_variant_id":1,
         "product_id":1,
         "item_sku":null,
         "variant_external_id":null,
         "sku":"aaaa",
         "product":{
            "brand":"test_brand"
         },
         "product_options":[
            
         ],
         "product_images":[
            
         ],
         "discounts":null,
         "created_at":"2021-04-23 02:05:10",
         "updated_at":"2021-04-23 02:05:10"
      }
   ],
   "payments":[
      "EFTPOS",
      "TESTING"
   ],
   "receipt_is_email":false,
   "receipt_ref":"AxKCC244XX133",
   "receipt_email":"[email protected]",
   "created_at":"2021-04-23 02:05:10",
   "updated_at":"2021-04-23 02:05:10"
}