This document provides details of the Product API.
We recommend reading 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; the Product API should only be used for specific cases.
About the Product API
The Product API provides methods to list the different products, retrieve an individual product and create a new product.
Products vs. Product variants
Typically, a parent products in Ometria corresponds to a single product page on the ecommerce store.
See: Products, product listings and product variants
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).
We also recommend that clients using a custom importer make sure to always pass a product listing when passing a new product. This is particularly important if you want to create price drop campaigns.
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.
Special Price
Special price is used for products on sale at a discounted price.
Ometria uses 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:
|
Object |
Field |
Value |
|
special_price_dt_from |
Date the special price is valid from |
|
|
special_price_dt_to |
Date the special price is valid to |
|
|
special_price |
The special price |
To set all listing on a product on sale, set the following parameters:
|
Object |
Field |
Value |
|
special_price_dt_from |
Date the special price is valid from |
|
|
special_price_dt_to |
Date the special price is valid to |
|
|
special_price |
The special 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 for the listing which is 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.
|
Field |
Value |
Notes |
|
is_active |
TRUE |
This 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 |
|
Title |
Must be defined |
This must be the parent level product |
|
URL |
Must be defined |
This must be the parent level product |
|
is_in_stock |
TRUE or not defined Note: If the value is FALSE, Ometria will assume the product is out of stock. |
This must be the parent level product |
|
is_variant |
FALSE |
This must be the parent level product |
Product Methods
Product Objects
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. |
|
type |
string |
|
in |
path |
Response
|
200 OK |
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 object |
Request Parameters
|
product_id |
ID of product being created or updated. |
|
type |
string |
|
in |
path |
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.
|
Value |
Type |
Description |
Required |
|
@type |
string |
The value must be "product". This shows that this record represents a product object. |
Required |
|
id |
string |
The id of the product. |
Required |
|
title |
string |
Title of this product as displayed to customers. |
Required |
|
is_variant |
boolean |
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. |
|
|
price |
number (float) |
Default display price (account default currency / store). |
Required |
|
sku |
string |
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_from |
string (date-time) |
Optional. Datetime that the 'special price' is applicable from. Format YYYY-MM-DD HH:II:SS. |
|
|
special_price_dt_to |
string (date-time) |
Optional. Datetime that the 'special price' is applicable until. Format YYYY-MM-DD HH:II:SS. |
|
|
special_price |
number (float) |
Optional. Reduced price used in conjunction with special_price_dt_from and special_price_dt_to. |
|
|
is_active |
boolean |
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_stock |
boolean |
Is this product in stock? |
|
|
url |
string |
URL of the product's page. |
|
|
image_url |
string |
URL of the product's image. |
|
|
attributes |
array |
Array of ProductAttribute objects. |
|
|
listings |
array |
Array of ProductListing objects used to work out which stores this product is available in and any store specific details. |
|
|
properties |
object |
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.
|
Value |
Type |
Description |
Required |
|
type |
string |
The type of the attribute. |
Required |
|
id |
string |
The id of the attribute. |
Required |
|
label |
string |
The label of the attribute. |
Required |
Example
{
"id": "category:womens",
"label": "Womens",
"type": "category"
}
ProductListing:object
Describes an individual store listing for a product.
|
Value |
Type |
Description |
Required |
|
title |
string |
The title of the product. |
Required |
|
price |
number (float) |
The price of the product. |
Required |
|
store |
string |
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 |
|
currency |
string (3 chars) |
The currency for this product listing. Following ISO 4217. |
Required |
|
is_active |
boolean |
Is this product considered active on the site. E.g. is it visible and buyable? |
|
|
special_price |
number (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. |
|
|
url |
string |
The link to this product listing. |
|
|
image_url |
string |
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"
}
Comments
0 comments
Please sign in to leave a comment.