We recommend reading the following pages before integrating with Ometria:

The easiest and quickest way to add bulk order data to Ometria is to use the Push endpoint; the order endpoint should only be used for specific cases.

🚧

Updating an existing order

When updating an order, you need to push the whole order object, not just the fields you want to update.

Order currency

If you sell products in multiple currencies, then use the OrderExtended objects to make sure the currency converts correctly.

Where base currency is used, this is the currency your Ometria account is set to report in. Local currency is the currency the product was sold in.

Customer

You don’t have to associate all orders with customers, e.g. where the order was made in a store and the customer wasn't identified.

📘

Note

The ID in the OrderCustomer object is the Customer_ID detailed on the Contact object.

Order / customer merging

This table explains how different customers are processed:

Value(s) providedPre-existing in OmetriaAction
ID and emailNoA new customer profile is created.

The new profile has no marketing preferences associated with it.
ID and emailYesThe order is associated with an existing customer profile.
email onlyNoA new customer profile is created.

The new profile has no marketing preferences associated with it.
email onlyYesOrder is associated with existing profile.

If multiple matching emails exist with different customer_ids, the order will be associated with the record without a customer_id.

If a record doesn't exist with just email, a new profile is created. The new profile has no marketing preferences associated with it.
IDNoA new customer profile is created.

The new profile has no marketing preferences associated with it.
IDYesThe order is associated with an existing customer profile.
firstname and lastnameN/AThe order is created and not associated with any profile.

Store IDs

The store identifier (used in orders and in the JavaScript tracker) can be any string value.

We recommend using the sites domain name (e.g. example.com).

If your store has variable 'sub-stores' (i.e. different territories) we recommend the naming convention / (e.g. example.com/en, example.com/de, etc.).

You can also use numeric store IDs if you have these defined, e.g. 123.

Currency exchange

When passing orders that are not in the account base currency, Ometria will convert the value using the currency exchange rate as supplied by openexchangerates.org.

The latest currency rates are retrieved by Ometria hourly.

Refunds

When processing refunds in Ometria, you need to take different actions depending on whether the order is partially or fully refunded.

When retrieving an order via the API, the value total_unit_quantity_refunded is automatically calculated by Ometria.

❗️

Note

Updating the order timestamps when refunding an order can affect the reporting.

  • If you want the reporting to show when the order was made, then do not update the timestamps.
  • If you want the reporting to show when the items were refunded, update the order timestamp.

Be aware that changing timestamps can trigger automation campaigns.

Partial Refunds

A partial refunds is where some, but not all of the products in an order are refunded.

In this case the following values need to be passed for each line item being refunded:

ValueDescription
quantity_refundedThe number of units (products) in the line item that have been refunded.
refundedThe total price of refunded products in this line item.
quantityThe quantity of the products purchased after the refunded units.
totalThe total price for the line item after the refunded units.
grand_totalThe grand total for the order after the refunded units are removed.
subtotalThe subtotal of the order after the refunded units are removed.
taxThe tax for the refunded line item.

Full Refund

A full refund is where all products purchased are refunded.

In this case, the whole order needs to be resubmitted with the following values set:

ValueDescription
is_validfalse
statusrefunded

Product merging

When passing orderlineitems, you can pass either the product_id or the sku.

If only the sku is passed, this is used to identify the right product in the database.

This table explains how orderlineitems are processed:

Values providedPre-existing in Ometria?Action
product_idNoA new product is created with the attributes passed in the orderlineitem.
product_idYesorderlineitem is associated with the existing product.
skuNoThe order is created, but the product is not created.

The order will contain the correct values, but you won't be able to report on the product.
skuYesorderlineitem is associated with the existing product.

🚧

Note

If no sku match is found and a product is created with a matching sku after the order event, the sku will not be retroactively matched.

To correct this, re-push the order after the product has been created.