This document provides details of the Push API.
We recommend that you read both the Data API Introduction page and the Ometria Data Architecture pages before integrating with Ometria.
The Push API passes Contacts, Orders, Products and Custom Events.
About the Push API
The Push API is the simplest way to send ecommerce data to Ometria. To use the Push API you send an HTTP POST request to the push endpoint containing a JSON formatted array of objects. Each object represents a record of type "order", "product" or "contact". Each record is identified by a unique ID. Records will be added if no record exists with that ID, otherwise the information in the object will be merged in with the fields in the current record and saved.
Creating New Records
Note: This API is designed to upload multiple records at once. You must ensure that you send a JSON formatted array of objects, even if you are only sending one record. A maximum of 100 records can be sent per call.
For example, the following JSON payload represents a single contact record being pushed to Ometria:
[{
"@type": "contact",
"id": "456",
"email": "example@example.com"
}]
Updating existing records
To update an existing record, you can send a partial record and only the supplied fields will be merged into the existing record.
For example, the following payload sets an existing order as "cancelled" and removes its revenue from Ometria's reporting:
[{
"@type":"order",
"id":"123551",
"status":"cancelled",
"is_valid":false
}]
The above order data could be submitted to Ometria via CURL using this command:
curl -X POST -H 'X-Ometria-Auth: YOUR_ACCESS_TOKEN' -H "Content-Type: application/json" -d '[{"@type":"order","id":"123551","status":"cancelled","is_valid":false}]' 'https://api.ometria.com/v2/push'
API responses
A successful response from the API looks like this:
{
"status":"OK",
"request_id":"e8d96762-7ee7-4c44-8ad4-48483712437f",
"accepted":1,
"rejected":0<span class="fr-marker" data-id="0" data-type="false" style="display: none; line-height: 0;"></span><span class="fr-marker" data-id="0" data-type="true" style="display: none; line-height: 0;"></span>
}
Requests are processed asynchronously, so the "OK" result doesn't mean that the records passed validation and were successfully inserted. It only means that the request was correctly received and authenticated by the API system. You can use the returned "request_id" to look at request status.
Handling errors
You can retrieve the 100 latest push record errors using the /push/_errors call:
curl -i -H 'X-Ometria-Auth: YOUR_ACCESS_TOKEN' https://api.ometria.com/v2/push/_errors
Push Methods
Push objects
Path
POST /push
Description
Accepts a list of up to 100 order/contact/product/custom event records as a list.
Request Body
Array<Contact> Array<Order> Array<Product> Array<custom_event> |
Push object |
Request Example
[
{
"@type": "order",
"billing_address": {
"city": "London",
"country_code": "GB",
"postcode": "W1K 4TG",
"state": "Greater London"
},
"channel": "online",
"coupon_code": "FJ45-TJ5Y-5YK3-T894",
"currency": "GBP",
"customer": {
"email": "john.smith@example.com",
"firstname": "John",
"lastname": "Smith"
},
"discount": -5,
"grand_total": 96.4,
"id": "123553",
"ip_address": "127.0.0.1",
"is_valid": true,
"lineitems": [
{
"product_id": "SS14-059493",
"properties": {
"custom_key": "custom value"
},
"quantity": 2,
"sku": "SS14-059493-S5",
"total": 100,
"unit_price": 50,
"variant_options": [
{
"id": "large",
"label": "Large",
"type": "size"
},
{
"id": "color-45",
"label": "Blue",
"type": "color"
}
]
}
],
"payment_method": "card",
"properties": {
"custom_key": "custom value"
},
"shipping": 2,
"shipping_address": {
"city": "London",
"country_code": "GB",
"postcode": "W1K 4TG",
"state": "Greater London"
},
"shipping_method": "standard",
"status": "complete",
"store": "example.com/en",
"subtotal": 83.33,
"tax": 16.07,
"timestamp": "2015-01-02T09:00:00+00",
"web_id": "891743"
}
]
Response
202 Accepted PushResponse |
Push object accepted |
403 Forbidden |
API key is not authorised to access this resource |
Response example (202 accepted)
{
"accepted": 1,
"rejected": 0,
"request_id": "c2da7180-52b2-11e7-92d6-0a3dc0ca7bee",
"skipped": 0,
"status": "OK"
}
List errors
Path
GET /push/_errors
Description
Return a list of the 100 latest push record errors
Response
200 OK Array<PushError> |
List of Errors object |
403 Forbidden |
API key is not authorised to access this resource |
Response Example (200 OK)
[
{
"message": {
"error_message": "not a valid value",
"error_path": "root > gender"
},
"record": {
"@source": "api",
"@type": "contact",
"account": 239,
"country_id": "GB",
"customer_id": "7898734",
"date_of_birth": "1985-01-05",
"email": "john.smith@example.com",
"firstname": "John",
"gender": 12,
"id": "123456",
"lastname": "Smith",
"marketing_optin": "EXPLICITLY_OPTEDIN",
"middlename": "Fredrick",
"prefix": "Mr",
"properties": {
"nickname": "Johnny",
"number_of_cats": 4
},
"timestamp_acquired": "2015-01-02"
},
"record_id": "123456",
"record_type": "contact",
"request_id": "ed926048-52af-11e7-aa8c-0a3dc0ca7bee",
"timestamp": "2017-06-16 16:22:06.705677+00"
}
]
PushError:object
Describes an individual error listing
Value |
Type |
Description |
Required |
request_id |
string |
The id of the request. |
|
record_type |
string |
The type of the pushed record. |
|
record_id |
string |
The id of the pushed record. |
|
record |
object |
Copy of the pushed record which raised an error. |
|
timestamp |
string (date-time) |
Datetime that the record was received. Format YYYY-MM-DDThh:mm:ss+Z. |
|
message |
Example
{
"message": {
"error_message": "not a valid value",
"error_path": "root > gender"
},
"record": {
"@source": "api",
"@type": "contact",
"account": 239,
"country_id": "GB",
"customer_id": "7898734",
"date_of_birth": "1985-01-05",
"email": "john.smith@example.com",
"firstname": "John",
"gender": 12,
"id": "123456",
"lastname": "Smith",
"marketing_optin": "EXPLICITLY_OPTEDIN",
"middlename": "Fredrick",
"prefix": "Mr",
"properties": {
"nickname": "Johnny",
"number_of_cats": 4
},
"timestamp_acquired": "2015-01-02"
},
"record_id": "123456",
"record_type": "contact",
"request_id": "ed926048-52af-11e7-aa8c-0a3dc0ca7bee",
"timestamp": "2017-06-16 16:22:06.705677+00"
}
PushErrorMessage:object
Describes what value is not correct and why
Value |
Type |
Description |
Required |
error_message |
string |
Description of the error. |
|
error_path |
string |
Location of the error within the pushed record. |
Example
{
"error_message": "Value must be at least 1 characters.",
"error_path": "root > attributes[1] > id"
}
PushRequest:object
An array of contact/order/product records.
Example
[
{
"@type": "contact",
"country_id": "GB",
"customer_id": "7898734",
"date_of_birth": "1985-01-05",
"email": "john.smith@example.com",
"firstname": "John",
"gender": "m",
"id": "123",
"lastname": "Smith",
"marketing_optin": "EXPLICITLY_OPTEDIN",
"middlename": "Fredrick",
"prefix": "Mr",
"properties": {
"nickname": "Johnny",
"number_of_cats": 4
},
"timestamp_acquired": "2015-01-02T09:00:00+00"
},
{
"@type": "contact",
"country_id": "US",
"customer_id": "524323",
"date_of_birth": "1990-04-12",
"email": "jane.doe@example.com",
"firstname": "Jane",
"gender": "f",
"id": "456",
"lastname": "Doe",
"marketing_optin": "EXPLICITLY_OPTEDOUT",
"prefix": "Miss",
"timestamp_acquired": "2012-05-01T23:00:00+00"
}
]
PushResponse:object
The outcome of a push request.
Value |
Type |
Description |
Required |
status |
string { OK, ERROR } |
Status of the request |
|
request_id |
string |
ID of the request |
|
accepted |
number |
Number of records accepted |
|
rejected |
number |
Number of records rejected, due to invalid format or data |
|
skipped |
number |
Number of records skipped, due to duplication |
Example
{
"accepted": 1,
"rejected": 0,
"request_id": "c2da7180-52b2-11e7-92d6-0a3dc0ca7bee",
"skipped": 0,
"status": "OK"
}
Comments
0 comments
Please sign in to leave a comment.