Push API

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

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

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

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

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

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.

Example

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