Introduction

This document provides details of the Product API. It is recommended that you read both the Data API Introduction page and the Ometria Data Architecture pages before integrating with Ometria. The easiest way to add product data to Ometria is to use the Push API and the Product API should only be used for specific cases.

Contents

About The Product API

The Product API provides methods to list the different products, retrieve an individual product and create a new product.

Products v Product variants

Typically, a parent products in Ometria corresponds to a single product page on the e-commerce store. A product may have multiple variant SKUs as children, these child products will not have their own individual URLs. It is recommended to pass all products and then set the product.is_variant parameter to true for all child products products (those without a unique URL).

Product IDs and SKUs

Often product ID and SKU will be the same value. However for some systems (e.g. where there is a separate product row identifier) these may be different.

Sale Prices

Sale prices use the special price from and to dates on the product and the special price in the listing.

To set a product without listings on sale, set the following parameters;

ObjectFieldValue
Productspecial_price_dt_fromDate the sale price is valid from

special_price_dt_toDate the sale price is valid to

special_priceThe sale price

To set all listing on a product on sale, set the following parameters;

ObjectFieldValue
Productspecial_price_dt_fromDate the sale price is valid from

special_price_dt_toDate the sale price is valid to
ProductListingspecial_priceThe sale price for that listing

To set specific listings on a product on sale, set the values as above, but do not set a special_price on the listing not on sale.

Product Recommendations

To ensure your products are used in the Ometria Product Recommendations engines, there is a set of criteria that must be met.

FieldCriteriaNotes
is_activeTRUEThis must be the parent level product

Price

>0 or
There must be a product listing in the same currency as the base currency for the account.
This must be the parent level product
TitleMust be definedThis must be the parent level product
URLMust be definedThis must be the parent level product
is_in_stockTRUE or not defined (must not be FALSE)This must be the parent level product
is_variantFALSEThis must be the parent level product

Product Methods

List Products

Get Product

Create Product

Product Objects

Product object

Product Attribute object

Product Listing object


List Products

Path

GET /products

Description

Return a list of products with optional filters

Request Parameters

limit

Number of items to return. Max 250.

type

string(default "10")

in

query

offset

Index of first record.

type

string(default "0")

in

query

active

Should we return only active or inactive products? true for return only active. false for return only inactive. If not defined, active and inactive products are returned.

type

string , x ∈ { true , false }

in

query

Responses

200 OK

Array<Product>

List of Product objects


403 Forbidden


API key is not authorised to access this resource


Response Example (200 OK)

[

  {

    "@type": "product"

    "attributes": [

      {

        "id": "category:womens",

        "label": "Womens",

        "type": "category"

      },

      {

        "id": "style:casual",

        "label": "Casual",

        "type": "style"

      }

    ],

    "id": "12345",

    "image_url": "http://www.example.com/product.jpg",

    "is_active": true,

    "listings": [

      {

        "currency": "EUR",

        "image_url": "http://www.example.com/fr/product.jpg",

        "is_active": true,

        "price": 50,

        "store": "example.com/fr",

        "title": "Produit d'essai",

        "url": "http://www.example.com/fr/product.html"

      },

      {

        "currency": "EUR",

        "image_url": "http://www.example.com/de/product.jpg",

        "is_active": false,

        "price": 50,

        "store": "example.com/de",

        "title": "Das Product",

        "url": "http://www.example.com/de/product.html"

      }

    ],

    "price": 50,

    "properties": {

      "custom_key": "custom value"

    },

    "sku": "FHSG-2738-FHI",

    "special_price": 45,

    "special_price_dt_from": "2015-03-02T09:00:00+00",

    "special_price_dt_to": "2015-01-02T09:00:00+00",

    "title": "Test Product",

    "url": "http://www.example.com/product.html"

  }

]



Get Product

Path

GET /products/{product_id}

Description

Returns a single Product item

Request Parameters

product_id

ID of product to fetch.

typestring
inpath

Response

200 OK
Product

Product object

403 Forbidden

API key is not authorised to access this resource

404 Not Found

Product with specified ID was not found

Response Example (200 OK)

{

  "@type": "product",

  "attributes": [

    {

      "id": "category:womens",

      "label": "Womens",

      "type": "category"

    },

    {

      "id": "style:casual",

      "label": "Casual",

      "type": "style"

    }

  ],

  "id": "12345",

  "image_url": "http://www.example.com/product.jpg",

  "is_active": true,

  "listings": [

    {

      "currency": "EUR",

      "image_url": "http://www.example.com/fr/product.jpg",

      "is_active": true,

      "price": 50,

      "store": "example.com/fr",

      "title": "Produit d'essai",

      "url": "http://www.example.com/fr/product.html"

    },

    {

      "currency": "EUR",

      "image_url": "http://www.example.com/de/product.jpg",

      "is_active": false,

      "price": 50,

      "store": "example.com/de",

      "title": "Das Product",

      "url": "http://www.example.com/de/product.html"

    }

  ],

  "price": 50,

  "properties": {

    "custom_key": "custom value"

  },

  "sku": "FHSG-2738-FHI",

  "special_price": 45,

  "special_price_dt_from": "2015-03-02T09:00:00+00",

  "special_price_dt_to": "2015-01-02T09:00:00+00",

  "title": "Test Product",

  "url": "http://www.example.com/product.html"

}



Create Product

Path

POST /products/{product_id}

Description

Create a new product or update an existing product

Request Body

Product

Product object

Request Parameters

product_id

ID of product being created or updated.

typestring
inpath

Responses

200 OK

Product object successfully created or updated

403 Forbidden

API key is not authorised to access this resource

Request Example

{

  "@type": "product",

  "attributes": [

    {

      "id": "category:womens",

      "label": "Womens",

      "type": "category"

    },

    {

      "id": "style:casual",

      "label": "Casual",

      "type": "style"

    }

  ],

  "id": "12345",

  "image_url": "http://www.example.com/product.jpg",

  "is_active": true,

  "listings": [

    {

      "currency": "EUR",

      "image_url": "http://www.example.com/fr/product.jpg",

      "is_active": true,

      "price": 50,

      "store": "example.com/fr",

      "title": "Produit d'essai",

      "url": "http://www.example.com/fr/product.html"

    },

    {

      "currency": "EUR",

      "image_url": "http://www.example.com/de/product.jpg",

      "is_active": false,

      "price": 50,

      "store": "example.com/de",

      "title": "Das Product",

      "url": "http://www.example.com/de/product.html"

    }

  ],

  "price": 50,

  "properties": {

    "custom_key": "custom value"

  },

  "sku": "FHSG-2738-FHI",

  "special_price": 45,

  "special_price_dt_from": "2015-03-02T09:00:00+00",

  "special_price_dt_to": "2015-01-02T09:00:00+00",

  "title": "Test Product",

  "url": "http://www.example.com/product.html"

}



Product: object

Describes a Product record.


ValueTypeDescriptionRequired
@typestring

The value must be "product". This shows that this record represents a product object.


Required
idstring

The id of the product.

Required
titlestring

Title of this product as displayed to customers.

Required
is_variantboolean

Whether or not this product record represents a variant product.


Note, variant products do not need to be created independently, they can be created as part of the order process.


pricenumber (float)

Default display price (account default currency / store).

Required
skustring

The SKU of the product.


Note, the SKU is not a key value in the Product object but is made available to users for reporting purposes.


special_price_dt_fromstring (date-time)

Optional. Datetime that the 'special price' is applicable from. Format YYYY-MM-DD HH:II:SS.


special_price_dt_tostring (date-time)

Optional. Datetime that the 'special price' is applicable until. Format YYYY-MM-DD HH:II:SS.


special_pricenumber (float)

Optional. Reduced price used in conjunction with special_price_dt_from and special_price_dt_to.


is_activeboolean

Is this product considered active on the site. E.g. is it visible and (in principle) buyable? Please use "is_in_stock" to indicate whether a product is in stock or not.



is_in_stockboolean

Is this product in stock?


urlstring

URL of the product's page.


image_urlstring

URL of the product's image.


attributesarray

Array of ProductAttribute objects.


listingsarray

Array of ProductListing objects used to work out which stores this product is available in and any store specific details.


propertiesobject

Custom key / value pairs accessible in emails using this product object



Example

{
  "@type": "product",
  "attributes": [
    {
      "id": "category:womens",
      "label": "Womens",
      "type": "category"
    },
    {
      "id": "style:casual",
      "label": "Casual",
      "type": "style"
    }
  ],
  "id": "12345",
  "image_url": "http://www.example.com/product.jpg",
  "is_active": true,
  "listings": [
    {
      "currency": "EUR",
      "image_url": "http://www.example.com/fr/product.jpg",
      "is_active": true,
      "price": 50,
      "store": "example.com/fr",
      "title": "Produit d'essai",
      "url": "http://www.example.com/fr/product.html"
    },
    {
      "currency": "EUR",
      "image_url": "http://www.example.com/de/product.jpg",
      "is_active": false,
      "price": 50,
      "store": "example.com/de",
      "title": "Das Product",
      "url": "http://www.example.com/de/product.html"
    }
  ],
  "price": 50,
  "properties": {
    "custom_key": "custom value"
  },
  "sku": "FHSG-2738-FHI",
  "special_price": 45,
  "special_price_dt_from": "2015-03-02T09:00:00+00",
  "special_price_dt_to": "2015-01-02T09:00:00+00",
  "title": "Test Product",
  "url": "http://www.example.com/product.html"
}

ProductAttribute:object


Describes an attribute attached to a Product.


ValueTypeDescriptionRequired
typestring

The type of the attribute.


Required
idstring

The id of the attribute.


Required
labelstring

The label of the attribute.


Required

Example

{
  "id": "category:womens",
  "label": "Womens",
  "type": "category"
}

ProductListing:object


Describes an individual store listing for a product.


ValueTypeDescriptionRequired
titlestring

The title of the product.

Required
pricenumber (float)

The price of the product.

Required
storestring

The store which the product belongs to.


The store must be unique for each listing within a product.


The store must match the store as named in the ecommerce platform for linking to the Javascript data.

See Store for more details.
Required
currencystring (3 chars)

The currency for this product listing. Following ISO 4217.

Required
is_activeboolean

Is this product considered active on the site. E.g. is it visible and buyable?


special_pricenumber (float)

A discounted price for this product, used in connection with special_price_dt_from and special_price_dt_to on the parent product object.


urlstring

The link to this product listing.


image_urlstring

The link to an image of this product.



Example

{
  "currency": "EUR",
  "image_url": "http://www.example.com/fr/product.jpg",
  "is_active": true,
  "price": 59.99,
  "store": "example.com/fr",
  "title": "Produit d'essai",
  "url": "http://www.example.com/fr/product.html"
}