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 require additional assistance with your particular use case please contact us for more information.
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.
The Ometria API has a default rate limit of 4 requests per second per Ometria account. If you expect to exceed this limit, please contact us.
In the case of your application being rate limited, the HTTP code 429 (too many requests) will be returned. In this case your application should reduce the number of requests it is trying to send.
Note: The asynchronous push API also has a maximum of 50,000 asynchronous import records. If you attempt to push more than this number of records in a short timeframe, you will also receive the HTTP 429 status code.
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).
Ecommerce data API
The Ometria API defines traditional REST endpoint for the main data objects we import (orders, products and contacts). 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.
Null values passed as “null” will populate a string field with Null.
Passing null, excluding “” will delete a value in the field
All ID fields in Ometria are string and cannot contain spaces.
The following API methods are available in the Ometria Data API suite. It is recommended that you start with the Push API for adding contacts, orders and products to Ometria.
|Authentication||Data Loading and Retrieval||Campaign Triggers|
Swagger For a copy of the swagger definition of our data API