Push API

Introduction

This document provides details of the Push API. It is recommended 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. Each of these objects are described in detail in their respective pages here:

Contents

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 does not 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

List Errors

Push Objects

Push Error object

Push Error Message object

Push Request object

Push Response object


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

ValueTypeDescriptionRequired
request_idstringThe id of the request.
record_typestringThe type of the pushed record.
record_idstringThe id of the pushed record.
recordobjectCopy of the pushed record which raised an error.
timestampstring (date-time)Datetime that the record was received. Format YYYY-MM-DDThh:mm:ss+Z.
messagePushErrorMessage

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

ValueTypeDescriptionRequired
error_messagestringDescription of the error.
error_pathstringLocation 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.

ValueTypeDescriptionRequired
statusstring { OK, ERROR }Status of the request
request_idstringID of the request
acceptednumberNumber of records accepted
rejectednumberNumber of records rejected, due to invalid format or data
skippednumberNumber of records skipped, due to duplication

Example

{
  "accepted": 1,
  "rejected": 0,
  "request_id": "c2da7180-52b2-11e7-92d6-0a3dc0ca7bee",
  "skipped": 0,
  "status": "OK"
}