This guide is designed to present a typical use case and will provide an overview of the steps involved in a custom integration.
If you need more help with your particular use case please contact us support by raising a ticket.
About the Data API
The Ometria API is organised around the REST methodology, and it uses resource-oriented URLs, and common HTTP response codes to indicate API errors.
All requests are authenticated using an API key which can be obtained from your account settings.
All requests to the Ometria API MUST be carried out via HTTPS.
API servers do not listen on unsecured HTTP ports to avoid the possibility of insecure information exchange.
The V2 Ometria API uses JSON encoding for all data exchanges and assumes UTF-8 character encoding throughout.
See: Default rate limits
There is a 60k byte limit per record for both our push API and REST endpoints.
If you exceed this limit, you will see the following error message "Payload invalid: Record is too large".
The Ometria API endpoints return results sorted by their internal Ometria ID in ascending order by default. This is unless the orderby=timestamp_update query parameter is specified, in which case results are returned sorted by datetime in ascending order.
There are typically two parts to a full Ometria integration:
Ecommerce data API: allows orders, products and contact data to be pushed via a REST endpoint and should be used to import historic data in a batch run as well as to push new data and updates in realtime. In addition to data collected from your ecommerce platform, it is also possible to push data that has been collected offline (for example, from a POS system).
This will allow for testing of the validity of any data pushed to our system, before moving to the live account (for which there is a different account hash and access token).
Ecommerce data API
We also define a Push API that allows easier batch upload. For most use cases the Push API will be simpler to work with.
We use historic data to build a single customer view, helping to maximise each customer’s lifetime value. When working on the staging account, it is recommended to import test data that is representative of your production dataset; using this as an opportunity to test that the data you have pushed to the Ometria API is passed correctly.
The data format used for uploading historic data is the same as that which is used for the realtime updates and using the Push API it is possible to send 100 records at once. It is also advised to import your entire product catalogue to the staging server, for the same purpose of ensuring that the data is passed correctly to Ometria.
It is best practice to push an order, product or contact object to Ometria as soon as you consider that order, product or contact is created. Following on from this, any subsequent changes to the order, product or contact should be pushed in real time where possible.
When pushing orders it is possible to add the products object inside of the orders object, however we recommend that products are pushed separately from orders and that they are referenced inside of an order by using the product id.
Where your products have variations it is important to include variant_options in the line items of the order object. This has a number of advantages inside of the Ometria platform, including allowing us to better recommend products to your customers.
For the available API calls, See Ecommerce Data API.
Once you are happy with the methods in place for pushing data and any issues have been resolved, we will generate an account hash and access token for your live account.
Entering null will populate a string field with null (i.e. empty), e.g.:
Passing null will delete a value in the field.
All ID fields in Ometria are string and cannot contain spaces.