Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.omneo.io/llms.txt

Use this file to discover all available pages before exploring further.

Transactions in Omneo represent completed purchases. Sending a transaction links it to a customer profile, contributes to aggregations (lifetime spend, ATV, purchase frequency), triggers reactions, and makes the transaction visible in Clienteling and Profile Portal.
Only sync completed transactions to Omneo. Do not sync draft, partially paid, or otherwise incomplete records. Omneo transactions are immutable records of what occurred.

​
Before you start

  • Review Authentication to get a bearer token
  • Plan your data mapping — decide which transaction fields from your source system map to Omneo fields
  • Determine whether you’ll look up profiles by Omneo ID, email, or an external identity handle

​
Transaction anatomy

A transaction has two levels:
  • Header — overall transaction details: total, date, location, staff, receipt ref, payments, tags
  • Items — individual line items with product, price, and quantity
Both header and items can be provided in the same request.

​
Resolving the profile ID

You don’t need to know the Omneo profile ID up front. Use profile_id_handle to tell Omneo how to interpret the profile_id field:
profile_id_handleBehaviour
(omitted)profile_id is treated as the Omneo profile UUID
"email"profile_id is treated as an email address
Any other stringprofile_id is treated as an identity value for that handle (e.g., "shopify")

​
Creating a transaction

curl -X POST https://api.[tenant].getomneo.com/api/v3/transactions \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "profile_id": "jane@example.com",
    "profile_id_handle": "email",
    "total": 149.95,
    "transacted_at": "2025-06-15 14:32:00",
    "timezone": "Australia/Melbourne",
    "external_id": "ORDER-10333",
    "receipt_ref": "659",
    "location_id": 2,
    "staff_id": 1993,
    "payments": ["EFTPOS"],
    "items": [
      {
        "name": "Linen Shirt",
        "product_variant_id": 333729,
        "quantity": 1,
        "price_current": 149.95,
        "price_sell": 149.95,
        "price_original": 149.95,
        "is_void": false
      }
    ]
  }'

​
Upsert (create or update)

Use the sync endpoint when you have a reliable external_id and want to avoid duplicate transactions: 
POST /api/v3/transactions/sync
This searches for an existing transaction matching external_id. If found, it updates it. If not found, it creates a new one.

​
Updating a transaction

curl -X PUT https://api.[tenant].getomneo.com/api/v3/transactions/{transactionId} \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "total": 99.95
  }'
Only the fields you include will be updated.

​
Voiding a transaction

Prefer voiding over deletion. Set is_void: true on the transaction to mark it as voided without removing it from history: 
curl -X PUT https://api.[tenant].getomneo.com/api/v3/transactions/{transactionId} \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "is_void": true
  }'

​
Bulk / queued transactions

For historical imports or high-volume ingestion, use the queue endpoint rather than the standard create endpoint. This places each transaction into a batch processing queue rather than processing it synchronously: 
POST /api/v3/transactions/queue
The request body is identical to the standard create endpoint. Loop through your records and submit them individually to the queue. A transaction.created webhook fires as each one processes.

​
Adding line items after creation

curl -X POST https://api.[tenant].getomneo.com/api/v3/transactions/{transactionId}/items \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Belt",
    "product_variant_id": 1,
    "quantity": 1,
    "price_current": 49.95,
    "price_sell": 49.95,
    "price_original": 49.95,
    "is_void": false
  }'
Note: adding items after the fact does not automatically adjust the transaction total. Update the header separately if needed.

​
Key fields reference

FieldRequiredNotes
totalYesFinal transaction total
transacted_atYesDatetime in UTC or with timezone
timezoneRecommendedIANA timezone string
external_idRecommendedYour system’s transaction ID
receipt_refRecommendedThe receipt number the customer knows
profile_idRecommendedLinks the transaction to a profile
location_idRecommendedOmneo location ID
staff_idOptionalOmneo staff ID
paymentsOptionalArray of payment method strings
itemsRecommendedArray of line items